Customization & Architecture

WooNuxt uses Nuxt Layers to separate core functionality from your customizations. This means you can override any component, page, composable, or style without touching the base layer — and safely pull in upstream updates without losing your changes.

How It Works

The project has two layers:

woonuxt/                    ← Your project (customize here)
├── app/
│   └── types/             ← Type overrides
├── nuxt.config.ts         ← Extends woonuxt_base
└── ...

woonuxt_base/              ← Core layer (do not edit directly)
├── app/
│   ├── components/        ← All default components
│   ├── composables/       ← All composables
│   ├── pages/             ← All pages
│   ├── queries/           ← All GraphQL queries
│   └── assets/css/        ← Base styles
└── nuxt.config.ts         ← Core Nuxt config

Your root nuxt.config.ts extends the base:

export default defineNuxtConfig({
  extends: ['./woonuxt_base'],
  // your overrides here
})

Nuxt merges both layers at build time, with your root-level files taking priority over woonuxt_base.

Overriding Components

To override any component, create a file with the same name in your root app/components/ folder:

# Example: override the default ProductCard
app/
└── components/
    └── productElements/
        └── ProductCard.vue   ← your version wins

You don't need to copy the original — just create a new file at the same path. The base layer version is completely replaced.

Example: Custom HeroBanner

<template>
  <section class="hero bg-primary text-white py-20">
    <h1 class="text-4xl font-bold">{{ title }}</h1>
    <p>{{ description }}</p>
  </section>
</template>

<script setup lang="ts">
defineProps<{ title: string; description: string }>()
</script>

Overriding Pages

Same principle — create a page at the same path:

app/
└── pages/
    └── index.vue    ← replaces woonuxt_base/app/pages/index.vue

Overriding Styles

Add custom CSS in app/assets/css/main.css. Tailwind CSS 4 is configured via PostCSS — extend the theme in your CSS directly:

@import "tailwindcss";

/* Extend or override Tailwind theme */
@theme {
  --color-primary: v-bind(primaryColor);
}

/* Your custom styles */
.my-custom-class {
  /* ... */
}

Adding Custom GraphQL Queries

Place .gql files in app/queries/. These are picked up automatically by nuxt-graphql-client:

query GetMyCustomData {
  # your query
}

Modifying nuxt.config.ts

Add modules, routes, or runtime config in the root nuxt.config.ts. It is merged with the base config, not replaced:

export default defineNuxtConfig({
  extends: ['./woonuxt_base'],

  // Add extra modules
  modules: ['@nuxtjs/google-fonts'],

  // Override runtime config
  runtimeConfig: {
    public: {
      PRODUCTS_PER_PAGE: 12,
    },
  },

  // Add custom routes
  hooks: {
    'pages:extend'(pages) {
      pages.push({ name: 'custom', path: '/custom', file: '~/app/pages/custom.vue' })
    },
  },
})

What Should NOT Be Edited

Avoid editing files inside woonuxt_base/ directly. Changes there will be lost when you pull upstream updates. If you need to change base behavior:

• Components → copy to app/components/ with the same path
• Composables → copy to app/composables/ and adjust imports
• Config → override in root nuxt.config.ts