Astro-based App Project Structure

This article describes the structure of an app project that uses the Astro-based Wix CLI, an earlier version of the CLI for app projects. The project is built on the Astro web framework, and declares its extensions with the @wix/astro package.

An Astro-based app project includes Astro files, Wix-specific files, Wix skills, and directories for extensions and configuration.

Project file structure

An Astro-based app project centers on extensions and the extensions.ts file that registers them.

Skills directories

New CLI projects include Wix skills so AI agents can perform CLI tasks for you. The skills are installed under .agents/skills/, with one folder per skill (such as wix-app and wix-headless), and made available to the AI tools you use, such as Claude Code, Cursor, and GitHub Copilot. The CLI also generates agent-instruction files, such as AGENTS.md and CLAUDE.md, for those tools.

.wix/

Contains configuration and log files related to the Wix environment.

src/

Source directory. Contains all the source code and core resources of your project.

pages/

pages/ holds backend HTTP endpoints under pages/api/, where each .ts file is auto-discovered as a route. For example, src/pages/api/users.ts is served at /api/users.

extensions/

The default location for extensions you generate with wix generate, organized by type to maintain consistency. Each extension gets its own folder holding an <extension-name>.extension.ts configuration file and its implementation. For example, an event handler is created at src/extensions/backend/events/my-event/, with my-event.extension.ts and my-event.ts.

You can place extensions anywhere under src/, as long as you update their paths in extensions.ts.

Each extension's .extension.ts file declares it with a builder from @wix/astro/builders, and extensions.ts imports the file and registers the extension. For example:

wix generate creates each extension's files, including a .extension.ts file containing the builder. By default, it uses the naming pattern [extension-name].extension.ts, and you can rename these files.

extensions.ts

The configuration file where you register all your project's extensions. It must be located in the src/ directory. It imports and registers each extension, wherever the extension lives under src/. When you move an extension file, update its import path here to maintain the connection. To see the extensions you can add, run wix generate.

The file uses a builder pattern syntax that allows you to chain extension configurations together. It follows this basic structure, where extensionType stands for the builder of the extension you register, such as dashboardPage:

The file:

• Imports the necessary builders from @wix/astro/builders.
• Exports a default app configuration.
• Uses the .use() method to register extensions.

extensions.ts can also import an extension that's declared in its own .extension.ts file, described under extensions/. For example:

When wix generate creates an extension, it adds the import statement and the .use() method call that register the new extension in extensions.ts.

When you delete an extension, remove both its import statement and its .use() method call from extensions.ts.

astro.config.mjs

Astro configuration file, including the wix() integration settings.

.env.local

Contains environment variables required to setup authentication for your local development environment. Don't edit any of the WIX_CLIENT variables.

wix.config.json

Defines the identifiers that connect your local code to your Wix project. Don't edit this file.

Other files and directories

The rest of the project uses standard Astro, npm, TypeScript, and Git files that you rarely need to edit:

• .astro/: holds Astro's build and type files, managed by Astro.
• dist/: your project's production build output, created when you build the project.
• node_modules/: the npm dependencies installed for your project.
• public/: holds static assets served at your site's root.
• src/env.d.ts: provides TypeScript type declarations for the Astro environment.
• .nvmrc: the version of Node.js the project uses, which Node Version Manager (NVM) reads when you run nvm use.
• package.json: manages your project's dependencies and scripts.
• tsconfig.json: configures the TypeScript compiler.
• .gitignore: lists the paths Git excludes from version control.