This article describes the structure of a Wix CLI headless project. The CLI uses a standardized project structure based on the Astro web framework.
A headless project includes Astro files, Wix-specific files, Wix skills, directories for extensions and configuration, and an Astro frontend for the site you build: pages, components, layouts, and more.
A headless project contains the Astro frontend for the site you build, and can also include dashboard and backend extensions, in an extensions/ folder registered by extensions.ts. Its frontend files under src/ depend on the template you start from.
Note: The CLI creates some of these folders and files as you work. For example, .astro/, dist/, and node_modules/ are created when you install dependencies or build and run your project.
| Folder or file | What it's for | Details |
|---|---|---|
.agents/skills/ | The Wix skills that let AI agents perform CLI tasks for you, with one folder per skill, such as wix-app and wix-headless. The skills are 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. | |
.astro/ | Astro's build and type files, managed by Astro. | |
.wix/ | Configuration and log files related to the Wix environment. This directory contains internal data. Don't edit it. | |
dist/ | Your project's production build output, created when you build the project. | |
node_modules/ | The npm dependencies installed for your project. | |
public/ | Static assets served at your site's root. | |
src/ | The source directory, with all the source code and core resources of your project. | |
src/extensions/ | The default location for the extensions you generate, one folder per extension. | src/extensions/ |
src/pages/ | Your frontend routes, one page per .astro file, and your backend HTTP endpoints under src/pages/api/. | src/pages/ |
| Frontend files | 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 Astro Templates for Wix-Managed Headless. | |
.env.local | Environment variables required to set up authentication for your local development environment. Don't edit any of the WIX_CLIENT variables. | |
.gitignore | Lists the paths Git excludes from version control. | |
astro.config.mjs | The Astro configuration file, including the wix() integration settings. | |
package.json | Your project's dependencies and scripts. | |
src/env.d.ts | TypeScript type declarations for the Astro environment. | |
src/extensions.ts | Registers all your project's extensions. | extensions.ts |
tsconfig.json | Configures the TypeScript compiler. | |
wix.config.json | Defines the identifiers that connect your local code to your Wix project. Don't edit this file. |
Last updated: 10 November 2026