This article describes the structure of a Wix CLI project. The CLI uses a standardized project structure based on the Astro web framework for both headless and app projects.
Every CLI project includes Astro files, Wix-specific files, Wix skills, and directories for extensions and configuration. A headless project additionally includes an Astro frontend for the site you build, with pages, components, layouts, and more.
Most of the structure is common to both headless and app projects. The main difference is the contents of src/.
Note: The CLI creates some of these directories as you work. For example, .astro/, dist/, and node_modules/ are created when you install dependencies or build and run your project.
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.
Contains configuration and log files related to the Wix environment.
Caution: This directory contains internal data. Don't edit it.
Source directory. Contains all the source code and core resources of your project. Its contents differ between headless and app projects. A headless project contains an Astro frontend for the site you build, while an app project centers on extensions. Both can contain extensions.
In a headless project, pages/ holds your frontend routes. Each .astro file is a page, such as pages/index.astro for your home page.
In both headless and app projects, pages/ also 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.
Beyond pages/, a headless project's frontend includes components and other supporting files under src/, such as layouts and styles. The exact set follows standard Astro conventions and depends on the template you start from. For what each template includes, see Wix-Managed Headless Templates.
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.
The configuration file where you register all your project's extensions. 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.
Astro configuration file, including the wix() integration settings.
Contains environment variables required to setup authentication for your local development environment. Don't edit any of the WIX_CLIENT variables.
Defines the identifiers that connect your local code to your Wix project. Don't edit this file.
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.package.json: manages your project's dependencies and scripts.tsconfig.json: configures the TypeScript compiler..gitignore: lists the paths Git excludes from version control.Last updated: 9 July 2026