Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 32 ยท First steps

Project structure and conventions

Tour the Nuxt folder layout: app, pages, components, composables, server, public, nuxt.config.ts and the generated .nuxt folder, and what each one does.

Nuxt finds your code by where it lives. A file in pages/ is a page, a file in server/api/ is an API endpoint, a file in public/ is served as it is. You rarely register anything. This only works if you know the folders, so this lesson is a map of a fresh project, with a note on what is generated and what you should never edit.

The layout below is the one used by current Nuxt versions, where application code sits inside an app/ folder. Older projects (Nuxt 3 without that setting) keep the same folders at the project root. The names and rules are the same either way, so the lessons that follow just say pages/, components/ and so on.

Creating a project

These commands are real and read-only here, because the site cannot run Node tooling:

Terminal
npm create nuxt@latest my-site
cd my-site
npm install
npm run dev

The older form npx nuxi init my-site uses the same project template through Nuxt's command line tool, nuxi. The dev server runs on port 3000 by default and reloads as you edit. Two other scripts matter later: npm run build creates a production build and npm run generate pre-renders the site to static files.

The folder map

TEXT
my-site/
  nuxt.config.ts          framework settings
  package.json
  app/
    app.vue               root component
    app.config.ts         settings that can change at runtime in the browser
    error.vue             custom error page
    pages/                routes (file-based routing)
    layouts/              page frames: header, footer, sidebar
    components/           auto-imported components
    composables/          auto-imported useSomething() functions
    middleware/           route guards that run before navigation
    plugins/              code that runs when the app starts
    utils/                auto-imported helper functions
    assets/               files processed by the build (CSS, images, fonts)
  server/
    api/                  endpoints under /api
    routes/               endpoints at any other path
    middleware/           runs on every request
    plugins/              server startup code
    utils/                auto-imported helpers for server code
  shared/                 code usable from both app and server
  public/                 files served as they are (favicon, robots.txt)
  .nuxt/                  generated, do not edit
  .output/                production build, do not edit

You will not create every folder. Start with app/app.vue and add pages/, components/ and the rest when you need them.

Three homes for your code

app/ Everything that renders in the browser.
server/ Endpoints and code that runs only on the server.
public/ Files served exactly as they are.
1 / 2

app/ - the part that runs in the browser

  • app.vue is the root component. With pages enabled it usually holds only <NuxtLayout> and <NuxtPage />. If your site has no pages/ folder at all, Nuxt skips the router completely and app.vue is the whole app.
  • pages/ holds one component per route (File-based routing).
  • layouts/ holds shared page frames (Nested routes and layouts).
  • components/ holds reusable pieces, imported automatically (Auto-imports).
  • composables/ and utils/ hold functions that are also imported automatically.
  • middleware/ holds route guards, such as "redirect guests to the login page".
  • plugins/ holds code that runs once when the app starts (Plugins and modules).
  • assets/ holds files that go through the build, such as global CSS or images you import (Head, SEO and assets).

server/ - the part that runs only on the server

Files in server/api/ become endpoints that begin with /api, and files in server/routes/ become endpoints at the path you give them. This code never ships to the browser, so it can safely read secrets and talk to a database (Server routes and the Nitro engine).

public/ - served as is

A file public/robots.txt is served at /robots.txt, and public/logo.png at /logo.png. There is no processing and no renaming, which is what you want for files whose URL must not change.

shared/

Code in shared/ (for example types or small validation helpers) can be used from both app/ and server/, so you do not duplicate it.

nuxt.config.ts

The config file lives at the project root and controls the framework. It is TypeScript, and defineNuxtConfig gives you autocompletion:

TypeScript
// nuxt.config.ts (read-only)
export default defineNuxtConfig({
  compatibilityDate: '2025-07-15',
  devtools: { enabled: true },
  modules: ['@nuxt/image'],
  css: ['~/assets/css/main.css'],
  runtimeConfig: {
    apiSecret: '',            // server only
    public: { siteName: 'My Site' },   // also sent to the browser
  },
  routeRules: {
    '/': { prerender: true },
  },
})

Each key has its own later lesson: modules (Plugins and modules), css (Styling), runtimeConfig (Runtime config) and routeRules (Rendering modes). The value of compatibilityDate is the date you created the project; it lets the platform keep behavior stable when Nuxt changes defaults.

There is a second file with a confusingly similar name. app.config.ts holds values such as theme colors that can be read in the browser and updated without rebuilding. Put secrets in neither: secrets belong in runtimeConfig, outside public.

The generated .nuxt folder

When you run npm install or npm run dev, Nuxt writes a hidden folder called .nuxt/. It contains the generated route table, the list of auto-imports, TypeScript declarations and the dev build. This is why your editor knows that ref or ProductCard exist even though you did not import them, and why tsconfig.json in the project just extends a file inside .nuxt/.

Two practical rules:

  • Do not edit or commit .nuxt/. It is rebuilt every time. If something looks stale (editor errors about auto-imports, for instance), delete it and run npx nuxt prepare, which regenerates the types.
  • .output/ is different: it is the result of npm run build, the folder you deploy (Building and deploying Nuxt).

Convention over configuration, in practice

Think of the conventions as a contract. You promise to put things in the right places, and Nuxt promises to wire them up. The first stand-in plays the "find where it belongs" role: given a file path, it reports what Nuxt would treat that file as. It uses a few of the real rules, including the HTTP-method suffix for server files (products.get.ts). It covers only some folders, as a model.

JS What does Nuxt make of this file?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice the last line. A file in a folder Nuxt does not know about is simply ignored, which is also why putting a component in app/helpers/ means it will not be auto-imported.

Mapping files to routes

Routing is the convention you will use most. The second stand-in turns a list of page files into routes, including the generated route name, which Vue Router uses for named navigation. Edit the list and rerun it to see the effect of an index.vue, a dynamic [id] folder and a nested file.

JS From page files to route names

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The real route table also records nesting and options set with definePageMeta. The next lesson, Auto-imports, explains the second big convention.

Common mistakes

  • Putting pages in the wrong folder. With the app/ layout, a stray pages/ at the project root is ignored.
  • Creating pages/ just to hold one page. Adding that folder switches on the router. That is fine, but remember to add <NuxtPage /> to app.vue.
  • Importing from .nuxt/ by hand. Use the documented aliases like ~/ for the app folder and #imports for auto-imports.
  • Storing secrets in public/ or app.config.ts. Both reach the browser.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A file at public/robots.txt is available at which URL?

    Files in public/ are served from the site root with no processing.
  2. 2. Which folder holds code that never reaches the browser?

    server/ code runs only in Nitro on the server. The others are part of the app or are served to visitors.
  3. 3. What is the .nuxt folder for?

    .nuxt is regenerated on every run. The deployable build is .output.
  4. 4. Which file would you use for a secret API key that must stay on the server?

    Keys in runtimeConfig are server-only unless placed under public. app.config.ts and public/ are visible to visitors.

Summary

  • app/ is code for the browser, server/ is code for Nitro, and public/ is served untouched.
  • Folder names carry meaning: pages, layouts, components, composables, middleware, plugins and utils each have a job.
  • nuxt.config.ts configures the framework; app.config.ts holds values that may be read in the browser.
  • .nuxt/ is generated and .output/ is the production build; never edit either.
  • Following the conventions replaces registration code and route tables.

Next, Auto-imports shows how Nuxt makes components and functions available without import lines.