Getting Started

Maravilla is an edge runtime platform that lets you deploy full-stack web applications with built-in platform services like KV storage and a document database. It runs your app with sub-100ms cold starts.

Prerequisites

• Node.js >= 22.12.0 (required for the CLI and build tooling)
• A supported platform: Linux x64, macOS x64/arm64, or Windows x64

Install the CLI

npm install -g @maravilla-labs/cli

To see installation progress with npm 7+, add the --foreground-scripts flag:

npm install -g @maravilla-labs/cli --foreground-scripts

Verify the installation:

maravilla --version

Initialize a project

Run maravilla init inside an existing project to set up the Maravilla configuration:

maravilla init

This detects your framework and scaffolds the necessary adapter configuration and project structure.

Start the dev server

Launch the local development environment, which starts the platform dev server (KV, Database) alongside your framework’s dev server:

maravilla dev

Your app runs on http://localhost:5173 with platform services available on port 3001. Hot module replacement works as usual.

Build for production

Create an optimized production bundle:

maravilla build

This produces a .maravilla/ directory containing your server bundle, static assets, and a platform manifest. You can preview the build locally:

maravilla preview

Deploy

Push your code to trigger a CI/CD pipeline build. Maravilla uses a .maravilla/pipeline.yml file to define build steps and deployment configuration. A typical pipeline installs dependencies, runs npm run build, and produces the .maravilla/ artifact for deployment.

Next steps

• Installation — system requirements, authentication, and project structure details
• Frameworks — set up SvelteKit, React Router, SolidStart, or TanStack Start