Nuxt•3mo ago

Structuring nuxt 3 to be modular

hi everyone, i have a question and wanted to discuss, how to truly structure our nuxt 3 application to be modular and module based. i am building an saas app that has so many different module that can be installed by the user. how do i structure the app so that different team can work on different module at the same time without interfering one another? should i use layer? because each module will have different sidebar menu, pages, etc. but they all share the same based component.

18 Replies

kapa.ai•3mo ago

Hi @CR. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- To structure a Nuxt 3 application for true modularity—especially for a SaaS with many installable modules, each potentially with its own sidebar, pages, and menus, but sharing base components—the recommended approach is to leverage Nuxt Layers and the modules system. Nuxt Layers allow you to encapsulate features, pages, components, and configuration in isolated, reusable units. Each layer can have its own components/, pages/, layouts/, and more, just like a full Nuxt app. You can then extend from one or multiple layers in your main app, making it easy for different teams to work independently on different modules without interfering with each other. Layers are ideal for sharing base components and configuration, while allowing each module to override or extend as needed. This approach also supports Domain-Driven Design (DDD) and large-scale modular architectures, which fits your SaaS scenario well. Layers can be local, in a monorepo, or even distributed via npm or git for maximum flexibility and team autonomy Nuxt Layers Guide, Authoring Nuxt Layers. Nuxt Modules are another way to encapsulate functionality, especially for logic, plugins, and integrations. Modules can register their own pages, components, and server routes, and can be auto-registered from the modules/ directory. This is useful for features that are more about extending the core or providing shared utilities, but for UI and page structure, layers are generally more powerful and flexible Nuxt Modules Guide, Directory Structure: modules/. Practical Structure Example: - layers/base/ – shared components, layouts, and configuration - layers/module-a/ – pages, sidebar, and features for Module A - layers/module-b/ – pages, sidebar, and features for Module B - app/ – your main application, which extends from the base and any active modules Your nuxt.config.ts might look like:

export default defineNuxtConfig({
  extends: [
    './layers/base',
    './layers/module-a',
    './layers/module-b'
  ]
})

export default defineNuxtConfig({
  extends: [
    './layers/base',
    './layers/module-a',
    './layers/module-b'
  ]
})

This setup allows each team to work in their own layer, with clear boundaries and minimal risk of conflicts. You can also override or extend files from layers as needed, and even enable/disable modules dynamically if you build your layer logic accordingly. Summary:
- Use Nuxt Layers for modular, feature-based code organization and team autonomy. - Use Nuxt Modules for shared logic, integrations, and utilities. - Both systems are designed for large, modular, and collaborative projects like SaaS platforms. For more details and examples, see the official documentation on Nuxt Layers and Authoring Nuxt Layers. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3mo ago

<@224493556373520384> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

CROP•3mo ago

@kapa.ai how should i structure the module?

kapa.ai•3mo ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- To structure a module in Nuxt 3, you have two main options: Nuxt Layers and local Nuxt modules. Both approaches are supported and can be combined, depending on your needs. --- 1. Nuxt Layers A Nuxt layer is essentially a partial Nuxt application. Each layer can have its own directory structure, including components/, pages/, layouts/, composables/, and its own nuxt.config.ts. This makes it ideal for encapsulating a feature or module, such as a SaaS module with its own sidebar, pages, and logic. Example structure for a layer:

layers/
  my-module/
    components/
    pages/
    layouts/
    composables/
    nuxt.config.ts

layers/
  my-module/
    components/
    pages/
    layouts/
    composables/
    nuxt.config.ts

To use a layer, add it to the extends array in your main nuxt.config.ts:

export default defineNuxtConfig({
  extends: [
    './layers/my-module'
  ]
})

export default defineNuxtConfig({
  extends: [
    './layers/my-module'
  ]
})

Each layer can override or extend files from other layers or the main app. This allows teams to work independently on different modules, each with its own structure and features, while sharing base components from a common layer if needed. Layers are especially recommended for modular, feature-based architectures in large projects like SaaS platforms Authoring Nuxt Layers. --- 2. Local Nuxt Modules You can also create a module as a local Nuxt module in the modules/ directory. A module is typically a TypeScript file (or a folder with an index.ts) that uses the defineNuxtModule helper. Modules are great for encapsulating logic, registering plugins, adding server routes, or even auto-registering components. Example structure for a local module:

modules/
  my-module/
    index.ts
    runtime/
      api-route.ts

modules/
  my-module/
    index.ts
    runtime/
      api-route.ts

Sample index.ts for a module:

import { defineNuxtModule, addServerHandler } from 'nuxt/kit'
export default defineNuxtModule({
  meta: { name: 'my-module' },
  setup () {
    // Register server routes, plugins, etc.
    addServerHandler({
      route: '/api/hello',
      handler: './runtime/api-route'
    })
  }
})

import { defineNuxtModule, addServerHandler } from 'nuxt/kit'
export default defineNuxtModule({
  meta: { name: 'my-module' },
  setup () {
    // Register server routes, plugins, etc.
    addServerHandler({
      route: '/api/hello',
      handler: './runtime/api-route'
    })
  }
})

Files in modules/ are auto-registered and executed in alphabetical order. You can organize modules as folders (with an index.ts) or as single files. This approach is best for logic and backend features, but less suited for encapsulating UI and pages compared to layers Directory Structure: modules/. --- Summary Table | Use Case | Recommended Structure | |-------------------------|---------------------------| | UI, pages, layouts | Nuxt Layer | | Logic, plugins, routes | Local Nuxt Module | | Both | Combine Layers & Modules | For a SaaS app with installable modules, Nuxt Layers are generally the best fit for modular UI and feature encapsulation, while local modules are ideal for shared logic and backend features. For more details and examples, see the official docs on Authoring Nuxt Layers and modules directory. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3mo ago

<@224493556373520384> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

CROP•3mo ago

@kapa.ai how should i structure the folder?

kapa.ai•3mo ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- To structure a modular Nuxt 3 application—especially for a SaaS with installable modules—the recommended folder structure leverages the new Nuxt 4 directory conventions and Nuxt Layers. Here’s how you should organize your folders: --- Recommended Folder Structure

.output/
.nuxt/
app/
  assets/
  components/
  composables/
  layouts/
  middleware/
  pages/
  plugins/
  utils/
  app.config.ts
  app.vue
  router.options.ts
content/
layers/
  module-a/
    components/
    pages/
    layouts/
    nuxt.config.ts
  module-b/
    components/
    pages/
    layouts/
    nuxt.config.ts
modules/
public/
server/
  api/
  middleware/
  plugins/
  routes/
  utils/
nuxt.config.ts

.output/
.nuxt/
app/
  assets/
  components/
  composables/
  layouts/
  middleware/
  pages/
  plugins/
  utils/
  app.config.ts
  app.vue
  router.options.ts
content/
layers/
  module-a/
    components/
    pages/
    layouts/
    nuxt.config.ts
  module-b/
    components/
    pages/
    layouts/
    nuxt.config.ts
modules/
public/
server/
  api/
  middleware/
  plugins/
  routes/
  utils/
nuxt.config.ts

- app/: Your main application code (shared components, layouts, etc.). - layers/: Each module (feature, team, or SaaS add-on) can be a layer with its own components/, pages/, layouts/, and nuxt.config.ts. This allows teams to work independently and encapsulate features. - modules/: For local Nuxt modules (logic, plugins, server handlers). - server/: For API routes, middleware, and server utilities. - public/: Static assets. - content/: For content files (if using Nuxt Content). With this structure, you can extend layers in your main nuxt.config.ts:

export default defineNuxtConfig({
  extends: [
    './layers/module-a',
    './layers/module-b'
  ]
})

export default defineNuxtConfig({
  extends: [
    './layers/module-a',
    './layers/module-b'
  ]
})

This approach is officially recommended for modular, scalable Nuxt projects and supports team autonomy and feature encapsulation New Directory Structure, Getting Started with Layers, Authoring Nuxt Layers. If you need to share base components or configuration, you can create a base/ layer and extend it in your modules and main app. --- Summary:
- Place shared code in app/ or a base/ layer. - Place each module in its own subfolder under layers/, with its own Nuxt structure. - Use modules/ for logic and backend features. This structure enables modular development and easy collaboration across teams. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3mo ago

<@224493556373520384> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

CROP•3mo ago

@kapa.ai can you gave an example of the root nuxt config and the module-a and module-b nuxt config?

kapa.ai•3mo ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- Certainly! Here’s an example of how you might structure the nuxt.config.ts files for the root project and for two modules (module-a and module-b) using Nuxt Layers, based on the official documentation: --- Root nuxt.config.ts This file extends both module-a and module-b layers:

export default defineNuxtConfig({
  extends: [
    './layers/module-a',
    './layers/module-b'
  ],
  app: {
    head: {
      title: 'My Modular SaaS App',
      meta: [
        { name: 'description', content: 'A modular Nuxt 3 SaaS application' }
      ]
    }
  }
})

export default defineNuxtConfig({
  extends: [
    './layers/module-a',
    './layers/module-b'
  ],
  app: {
    head: {
      title: 'My Modular SaaS App',
      meta: [
        { name: 'description', content: 'A modular Nuxt 3 SaaS application' }
      ]
    }
  }
})

Authoring Nuxt Layers
Getting Started with Layers --- layers/module-a/nuxt.config.ts This file can define configuration specific to Module A:

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        { name: 'module-a', content: 'Module A loaded' }
      ]
    }
  }
})

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        { name: 'module-a', content: 'Module A loaded' }
      ]
    }
  }
})

Authoring Nuxt Layers --- layers/module-b/nuxt.config.ts This file can define configuration specific to Module B:

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        { name: 'module-b', content: 'Module B loaded' }
      ]
    }
  }
})

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        { name: 'module-b', content: 'Module B loaded' }
      ]
    }
  }
})

Authoring Nuxt Layers --- Notes: - Each layer can have its own components/, pages/, layouts/, etc. - The root config can override or extend settings from the layers. - The extends array in the root config determines which layers are included and their order. This setup allows you to keep each module’s configuration and features isolated, while still sharing base components and configuration as needed. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3mo ago

<@224493556373520384> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

CROP•3mo ago

@kapa.ai why can't the root nuxt config auto registering the module inside the layers folder?

kapa.ai•3mo ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- The reason the root nuxt.config.ts does not auto-register modules inside the layers/ folder is due to how Nuxt's layer auto-registration works. According to the official documentation, Nuxt will automatically register any layers found in the ~~/layers directory as layers, but this auto-registration is specifically for layers, not for modules inside those layers. If you want to use a layer, you need to extend it explicitly in your root nuxt.config.ts using the extends property. Modules inside a layer are not auto-registered by the root project unless the layer itself is extended. Additionally, there was a known issue where the nuxt add layer command would create the layer inside the app/layers directory, which was not auto-registered by Nuxt. Only layers placed at the project root in the layers/ directory are auto-registered. This was later resolved, but it highlights that the auto-registration mechanism is sensitive to the correct directory placement and is only for layers, not for modules within those layers. If you want modules inside a layer to be registered, you must ensure the layer is properly extended in your root config, and then Nuxt will process the contents of that layer as part of your application structure, including its modules if they follow the expected conventions Getting Started with Layers Github Issue: nuxt add layer. In summary:
- The root config auto-registers layers in the root layers/ directory, not modules inside those layers. - You must explicitly extend a layer for its contents (including modules) to be included. - Directory placement is important for auto-registration to work as expected. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3mo ago

<@224493556373520384> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

CROP•3mo ago

@kapa.ai but the module also need to use from root app?

kapa.ai•3mo ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- Yes, if you want a module (in the Nuxt sense, such as a local module in modules/ or a module inside a layer) to be used by the root app, it must be registered or made available to the root app. - For local modules in the root modules/ directory:
These are auto-registered by Nuxt and do not require manual registration in nuxt.config.ts if they follow the correct file patterns (e.g., modules/*.ts or modules/*/index.ts) Directory Structure: modules/. - For modules inside a layer:
The root app must extend that layer in its nuxt.config.ts for the layer’s modules (and other features) to be included in the build. Once the layer is extended, Nuxt will process the layer’s modules/ directory and register those modules as part of the application. The modules inside the layer are not auto-registered by the root app unless the layer itself is extended Getting Started with Layers. So, to summarize:
- Yes, the module must be made available to the root app, either by being in the root modules/ directory or by being inside a layer that is extended by the root app.
- Extending a layer in the root config is what makes its modules available to the root app. If you do not extend the layer, the modules inside it will not be used by the root app. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3mo ago

<@224493556373520384> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

flapili•3mo ago

You could go multi app for frontend

Gaming

Programming

Structuring nuxt 3 to be modular

Did you find this page helpful?