directory-structure

251 notes in this subject, read out of this brain and free to use. This is page 3 of 5.

modules/ auto-registration patterns

Local modules in the modules/ directory are automatically registered if they follow these file patterns: modules/*/index.ts (modules in subdirectories with index.ts file) and modules/*.ts (modules as direct .ts files in the modules/ directory).

modules/ directory purpose

The modules/ directory is used to automatically register local modules within your application. You do not need to add local modules to nuxt.config.ts separately.

Local module runtime structure

All components, pages, composables, and other files that would normally be placed in the app/ directory must be placed in modules/your-module/runtime/app/. This ensures they can be type-checked properly.

nuxt/kit helper subpath import

The nuxt/kit helper subpath import provides utilities like addComponentsDir, addServerHandler, createResolver, and defineNuxtModule for defining local modules. Using nuxt/kit means you do not need to add @nuxt/kit to your project's dependencies separately.

public directory use cases

The public/ directory is suitable for files that must keep their exact names (such as robots.txt) or files that are unlikely to change (such as favicon.ico).

public directory example structure

A typical public/ directory contains files such as favicon.ico, og-image.png, and robots.txt at the root level.

referencing public directory assets

Assets in the public/ directory are referenced from code using the root path. For example, an og-image.png file in public/ is referenced as '/og-image.png'.

public directory purpose and behavior

The public/ directory is used to serve static assets for your website. Files in the public/ directory are served at the root of your site and are not modified by the build process.

Nuxt 2 static directory equivalent

In Nuxt 2, the public/ directory was known as the static/ directory.

shared/ auto-import file scanning rules

Only files in the shared/utils/ and shared/types/ directories will be auto-imported. Files nested within subdirectories of these directories will not be auto-imported unless you add these directories to imports.dirs and nitro.imports.dirs. The way shared/utils and shared/types auto-imports work is identical to app/composables/ and app/utils/ directories.

shared/ directory cannot import Vue or Nitro code

Code in the shared/ directory cannot import any Vue or Nitro code. This restriction exists because Nuxt builds two separate bundles (the Vue app and the Nitro server) that run in different contexts.

shared/ directory purpose and availability

The shared/ directory allows you to share code that can be used in both the Vue app and the Nitro server. The shared/ directory is available in Nuxt v3.14 and later.

shared/ usage in server routes example

Auto-imported utilities from shared/utils/ can be used directly in server routes. Example: In server/api/hello.get.ts, a capitalize function exported from shared/utils/capitalize.ts can be used directly as: export default defineEventHandler((event) => { return { hello: capitalize('hello') } }).

shared/ usage in Vue app example

Auto-imported utilities from shared/utils/ can be used directly in Vue components. Example: In app/app.vue, a capitalize function exported from shared/utils/capitalize.ts can be used directly as: const hello = capitalize('hello').

shared/ default export usage example

Export utilities from shared/utils/ using default exports. Example: export default function (input: string) { return input[0] ? input[0].toUpperCase() + input.slice(1) : '' }. These are then auto-imported in both the Vue app and server code.

shared/ named export usage example

Export utilities from shared/utils/ using named exports. Example: export const capitalize = (input: string) => { return input[0] ? input[0].toUpperCase() + input.slice(1) : '' }. These are then auto-imported in both the Vue app and server code.

Why Vue app code cannot be imported into Nitro

Components and composables need the Vue app runtime and often the Nuxt context (such as useNuxtApp() or useRoute()), neither of which exists in Nitro. Importing them into server code can cause build or runtime errors, and can pull the Vue app's dependencies into your server bundle.

Why Nitro code cannot be imported into the Vue app

Server-only code (such as Node APIs, Nitro utilities, or server route handlers) must not run in the browser. Importing it into your app can break the client build, cause runtime errors in the browser, or leak server logic into the client bundle.

Type-only imports in shared code

import type is erased at compile time and does not pull runtime code into the other bundle, so importing only types across the boundary may appear to work. However, keep shared types (such as API response types) in shared/types/ instead, where they are auto-imported in both contexts. This keeps the boundary clear, avoids accidentally turning a type import into a value import later, and matches Nuxt's separate type contexts for app, server, and shared code.

Context-specific types in app and server directories

Types that are only used in one context can live next to that context instead. app/types/ is auto-imported in the Vue app only, and server/types/ is auto-imported in the Nitro server only. Use shared/types/ when a type is needed in both contexts.

Manual imports from shared/ using #shared alias

Any files in the shared/ folder that are not auto-imported must be manually imported using the #shared alias, which is automatically configured by Nuxt. For files directly in the shared directory, use: import capitalize from '#shared/capitalize'. For files in nested directories, use: import lower from '#shared/formatters/lower'. For files nested in a folder within utils, use: import upper from '#shared/utils/formatters/upper'.

test/ directory subdirectories

The test/ directory typically contains three subdirectories: test/unit/ for fast Node tests without the Nuxt runtime, test/nuxt/ for tests that need the Nuxt runtime environment, and test/e2e/ for end-to-end tests against a running app.

@nuxt/test-utils for testing

The @nuxt/test-utils package is the recommended tool to use with the test/ directory for organizing and running tests in a Nuxt application.

runtimeConfig NUXT_ prefix requirement in production

In production, runtimeConfig will not pick up environment variables that don't start with NUXT_.

appConfig as alternative to .env

If you want to use environment variables set at build time but do not need to update them later (or only need to update them reactively within the app), appConfig may be a better choice than .env. appConfig can be defined both within nuxt.config (using environment variables) and within an ~/app.config.ts file in the project.

Static site runtime configuration limitation

For a purely static site, it is not possible to set runtime configuration after the project is prerendered.

Production preview alternative

Alternatively for production preview, pass environment variables as arguments using the terminal. Example for Linux or macOS: NODE_ENV=production DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs

Production preview with nuxt preview

For local production preview, use the nuxt preview command. This command loads the .env file into process.env for convenience and requires dependencies to be installed in the package directory.

.env file purpose

A .env file specifies build-time and dev-time environment variables for Nuxt projects. The file should be added to .gitignore to avoid pushing secrets to the repository.

.env automatic loading

Nuxt CLI has built-in .env support via c12. If a .env file exists in the project root directory, it will be automatically loaded at dev, build, and generate time. Environment variables set in .env will be accessible within the nuxt.config file and modules.

.env variable removal behavior

Removing a variable from .env or removing the .env file entirely will not unset values that have already been set.

Custom .env file with --dotenv flag

To use a different .env file such as .env.local or .env.production, pass the --dotenv flag when using the Nuxt CLI. Example: npx nuxt dev --dotenv .env.local

.env hot reload in development

When updating .env in development mode, the Nuxt instance is automatically restarted to apply new values to process.env.

Use Runtime Config instead of env variables

In application code, use Runtime Config instead of plain env variables.

.env files not read in production

After the server is built, .env files are not read in production. The developer is responsible for setting environment variables using the tools and methods provided by their hosting environment. This design ensures compatibility across various deployment environments, some of which may not have a traditional file system available, such as serverless platforms or edge networks like Cloudflare Workers.

Production environment variable methods

In production, environment variables can be set by: passing them as terminal arguments (e.g., NODE_ENV=production DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs), setting them in shell configuration files like .bashrc or .profile, or using cloud service provider interfaces such as Vercel, Netlify, and AWS dashboards or CLI tools.

.gitignore entry for Nuxt build output directory

The .output directory should be added to .gitignore as it contains Nuxt dev and build outputs.

Recommended .gitignore entries for Nuxt projects

A Nuxt project should include at least the following entries in the .gitignore file: .output, .data, .nuxt, .nitro, .cache, and dist (Nuxt dev/build outputs); node_modules (Node dependencies); logs and *.log (Logs); .DS_Store (Misc); .env, .env.* with an exception for !.env.example (Local env files).

.gitignore entry for Nuxt cache directories

The directories .nuxt, .nitro, and .cache should be added to .gitignore as they contain Nuxt dev and build outputs and cache files.

.nuxtignore file specification

The .nuxtignore file uses the same specification as .gitignore and .eslintignore files, where each line is a glob pattern indicating which files should be ignored.

.nuxtignore file purpose

The .nuxtignore file tells Nuxt to ignore files in your project's root directory during the build phase.

.nuxtignore example patterns

Examples of .nuxtignore patterns include: ignoring a specific layout file with 'app/layouts/foo.vue', ignoring layout files ending with '-ignore.vue' using 'app/layouts/*-ignore.vue', ignoring a specific page file with 'app/pages/bar.vue', ignoring pages in a folder with 'app/pages/ignore/*.vue', and ignoring middleware files with exceptions using 'app/middleware/foo/*.js' and '!app/middleware/foo/bar.js'.

.nuxtignore configuration options

You can also configure ignoreOptions, ignorePrefix, and ignore in your nuxt.config file to customize the ignore behavior.

.nuxtrc file purpose and syntax

The .nuxtrc file allows you to configure Nuxt with a flat syntax based on unjs/rc9. It provides an alternative to nuxt.config for simpler configurations.

Global .nuxtrc file location macOS and Linux

On macOS and Linux systems, the global .nuxtrc file is located at ~/.nuxtrc in the user's home directory.

Global .nuxtrc file location Windows

On Windows systems, the global .nuxtrc file is located at C:\Users\{username}\.nuxtrc.

.nuxtrc setups section automatic tracking

Nuxt automatically adds a setups section to the .nuxtrc file to track module installation and upgrade state. This section is used internally for module lifecycle hooks and should not be modified manually.

.nuxtrc example configuration

Example .nuxtrc file showing how to disable SSR, configure devtools, add Nuxt modules, and track module setups: ```bash # Disable SSR ssr=false # Configuration for `@nuxt/devtools` devtools.enabled=true # Add Nuxt modules modules[]=@nuxt/image modules[]=nuxt-security # Module setups (automatically added by Nuxt) setups.@nuxt/test-utils="3.23.0" ```

.nuxtrc configuration precedence

Configuration precedence in Nuxt follows this order from lowest to highest: global .nuxtrc file, project-level .nuxtrc file, nuxt.config file. Properties in nuxt.config will overwrite properties in .nuxtrc.

nuxt.config file extensions

The nuxt.config file can use the extensions .js, .ts, or .mjs.

nuxt.config.ts basic structure

The basic structure of a nuxt.config file exports a default function call to defineNuxtConfig with configuration options passed as an object argument.

Nuxt restarts on configuration file changes

Nuxt will perform a full restart when detecting changes in the main configuration file (nuxt.config), the .env file, the .nuxtignore file, or the .nuxtrc file.

defineNuxtConfig helper is globally available

The defineNuxtConfig helper is available globally without requiring an import statement. It can be explicitly imported from 'nuxt/config' if preferred.

Required dependencies for Nuxt

A Nuxt application requires three core dependencies: nuxt, vue, and vue-router.

Minimal package.json structure for Nuxt

A minimal Nuxt application package.json includes the name field (e.g., 'nuxt-app'), private set to true, type set to 'module', scripts for build, dev, generate, preview, and postinstall, and dependencies for nuxt, vue, and vue-router all set to latest versions.

package.json scripts in Nuxt

Standard Nuxt scripts are: 'build' runs 'nuxt build', 'dev' runs 'nuxt dev', 'generate' runs 'nuxt generate', 'preview' runs 'nuxt preview', and 'postinstall' runs 'nuxt prepare'.

package.json type field for Nuxt

The type field in package.json should be set to 'module' for Nuxt applications to use ES modules.

shared/ directory purpose

The shared/ directory contains shared code that can be used in both the Vue app and the Nitro server.

Root directory contains nuxt.config.ts

The root directory of a Nuxt application is the directory that contains the nuxt.config.ts file, which is used to configure the Nuxt application.

app/ directory structure and subdirectories

The app/ directory is the main directory of a Nuxt application and contains the following subdirectories: assets/ (website's assets that the build tool will process), components/ (Vue components), composables/ (Vue composables), layouts/ (Vue components that wrap pages and avoid re-rendering), middleware/ (code that runs before navigating to a route), pages/ (file-based routing), plugins/ (Vue plugins used at application creation), and utils/ (reusable functions).

Give your agent this brain