In This Article

Architecture and Project Structure

Wix-managed headless projects are built on a modern web development stack that combines the Astro framework, the Vite toolchain, and Wix hosting infrastructure. This article explains how these pieces fit together and what they mean for your project.

The Astro framework

Wix-managed headless projects use Astro as their foundation. Astro is a JavaScript-based web framework designed for building fast, content-focused websites.

There are several reasons Astro is a good fit for headless projects:

Backend rendering by default: Astro renders pages on the server, which means faster initial page loads and better SEO without extra configuration.
Partial hydration: Astro only sends JavaScript to the browser when a component actually needs interactivity. Static content ships as plain HTML with no JavaScript overhead, resulting in smaller bundle sizes and faster page loads.
No new language to learn: Everything in Astro is written in HTML, CSS, and JavaScript. There's no proprietary templating language.
Framework flexibility: Astro isn't locked to a single component framework. You can use React, Vue, Svelte, or Solid components alongside plain HTML, or mix and match frameworks in the same project. For example, you might use React for a dynamic shopping cart component while keeping the rest of your product pages in plain Astro.

For details on Astro's features and syntax, see the Astro documentation.

Project structure overview

When you create a Wix-managed headless project with the CLI, it generates an Astro project with Wix integration. Here are the key parts of the project:

src/: Your source code: Astro pages, components, layouts, and extensions.
src/extension.ts: Registers all extensions for your project.
public/: Static files served at the root of your project, such as images and fonts.
.wix/: Wix configuration and environment files.
astro.config.mjs: Astro configuration file.
wix.config.json: Defines your project's app ID and project ID.
.env.local: Environment variables for local development, including authentication credentials.

Your frontend is defined by standard Astro files: pages, components, and layouts. Extensions are organized in custom folders under src/ and registered in the extension.ts configuration file.

For the complete file structure reference, see Project Structure in the CLI documentation.

The Vite toolchain

Under the hood, the Wix CLI uses Vite as its build tool. Vite provides:

TypeScript support: Write your code in TypeScript with full IntelliSense and type checking.
Hot module replacement: Changes you make to your code are reflected in the browser without a full page reload during local development.
CSS modules and pre-processors: Use CSS modules, Sass, Less, or PostCSS out of the box.
Static asset handling: Import images and other assets directly in your code.

The CLI handles the setup, so you don't need to configure Vite yourself.

Your project's private app

When you create a Wix-managed headless project, the CLI sets up a private app behind the scenes. This app serves 2 important roles:

Authentication: The private app acts as the OAuth handler for your project. It's the reason you don't need to manually create an OAuth app or manage client credentials. The CLI configures the app's credentials and stores them in your project's environment variables.
Extensions: The private app is where your extensions are registered. When you add extensions, they're added to this app. The extension.ts file in your project is the configuration file for this app's extensions.

The private app is tied to your headless project and can't be shared with other projects or published to the Wix App Market. It exists to power your project's backend capabilities and authentication.

You can see the private app's ID in your wix.config.json file under the appId field.

Hosting infrastructure

Wix-managed headless projects are hosted on Wix serverless infrastructure. You don't manage any servers, containers, or deployment pipelines.

The hosting environment provides:

Global content delivery network (CDN): Your project is served from a CDN, ensuring fast load times for visitors worldwide.
Automatic SSL: SSL certificates are provisioned and renewed automatically, so your project is always served over HTTPS.
Serverless architecture: Scaling and resource allocation are handled automatically. Your project scales up during traffic spikes and scales down when demand decreases.
Session management middleware: A built-in middleware manages session tokens and cookies for site visitors. This is what enables features like persistent shopping carts and seamless authentication without you writing session management code.

For details on building and deploying to this infrastructure, see Development, Build, and Deployment.