Frameworks

Maravilla supports modern full-stack frameworks through dedicated adapters and a Nitro preset. Each integration produces a .maravilla/ build output that the runtime can serve at the edge.

SvelteKit

Fully supported via @maravilla-labs/adapter-sveltekit.

Install

npm install -D @maravilla-labs/adapter-sveltekit
npm install @maravilla-labs/platform

Configure

Update your svelte.config.js to use the Maravilla adapter:

import adapter from '@maravilla-labs/adapter-sveltekit';

const config = {
  kit: {
    adapter: adapter({
      out: 'build',         // Output directory (default: '.maravilla')
      precompress: false,    // Pre-compress static assets (default: false)
      polyfill: true         // Include polyfills (default: true)
    })
  }
};

export default config;

Adapter options

Use platform services

Access KV and Database in your server-side load functions:

// src/routes/+page.server.ts
import { getPlatform } from '@maravilla-labs/platform';
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async () => {
  const platform = getPlatform();

  // KV store
  const cached = await platform.env.KV.demo.get('homepage:data');

  // Document database (document queries)
  const users = await platform.env.DB.find('users', { active: true });

  return { cached, users };
};

React Router

Fully supported via @maravilla-labs/adapter-react-router. Works with React Router 7 (the framework formerly known as Remix).

Install

npm install -D @maravilla-labs/adapter-react-router
npm install @maravilla-labs/platform

Configure

Add the Maravilla Vite plugin to your vite.config.ts. The plugin runs after React Router’s build to produce the .maravilla/ bundle:

import { defineConfig } from 'vite';
import { reactRouter } from '@react-router/dev/vite';
import { maravillaReactRouter } from '@maravilla-labs/adapter-react-router/vite';

export default defineConfig({
  plugins: [
    reactRouter(),
    maravillaReactRouter({
      out: '.maravilla',           // Output directory (default: '.maravilla')
      serverBuildPath: 'build/server', // React Router server output (default)
      clientBuildPath: 'build/client', // React Router client output (default)
    })
  ]
});

Adapter options

Nitro-based frameworks (SolidStart, TanStack Start)

Frameworks built on Nitro are supported through @maravilla-labs/preset-nitro. This includes SolidStart and TanStack Start.

Install

npm install -D @maravilla-labs/preset-nitro
npm install @maravilla-labs/platform

SolidStart

Configure the Nitro preset in your app.config.ts:

import { defineConfig } from '@solidjs/start/config';

export default defineConfig({
  server: {
    preset: '@maravilla-labs/preset-nitro'
  }
});

TanStack Start

Configure the Nitro preset in your app.config.ts:

import { defineConfig } from '@tanstack/start/config';

export default defineConfig({
  server: {
    preset: '@maravilla-labs/preset-nitro'
  }
});

Standalone Nitro

You can also use the preset directly in a Nitro config:

// nitro.config.ts
export default defineNitroConfig({
  preset: '@maravilla-labs/preset-nitro'
});

The preset automatically detects which framework is in use (SolidStart, TanStack Start, or plain Nitro) and configures the build accordingly.

What About Next.js?

Next.js is not currently supported. The framework has historically been deeply coupled to Vercel’s proprietary infrastructure, making it impractical to run on alternative runtimes without relying on undocumented internals that break between releases.

Next.js 16.2 (March 2026) introduced a stable Adapter API, and the OpenNext working group — with Cloudflare, Netlify, AWS, and Google — is building verified adapters for non-Vercel platforms. This is a promising step toward true portability.

We are monitoring the Adapter API as it matures. Once the ecosystem stabilizes and verified adapters prove reliable in production, we will re-evaluate adding Next.js support. In the meantime, React Router provides a fully supported alternative for React-based applications on Maravilla.

Platform services across frameworks

Regardless of framework, use @maravilla-labs/platform to access platform services in server-side code:

npm install @maravilla-labs/platform

The platform client auto-detects whether it is running in development (connecting to the local platform dev server on port 3001) or production (using the runtime’s built-in services). Import and use it in any server-side handler:

import { getPlatform } from '@maravilla-labs/platform';

const platform = getPlatform();

// KV Store -- key-value storage with optional TTL
await platform.env.KV.demo.put('key', 'value', { expirationTtl: 3600 });
const value = await platform.env.KV.demo.get('key');

// Database -- document document operations
await platform.env.DB.insertOne('users', { name: 'Alice', active: true });
const users = await platform.env.DB.find('users', { active: true }, {
  sort: { createdAt: -1 },
  limit: 20
});

CI/CD pipeline

All frameworks use the same pipeline format. Place a pipeline.yml in your .maravilla/ directory:

name: build-and-deploy
image: node:22-alpine

on:
  push:
    branches: [main]

jobs:
  build:
    steps:
      - name: Install dependencies
        commands:
          - npm ci
      - name: Build app
        commands:
          - npm run build
    artifacts:
      paths: [build/]
    resources:
      cpu: "2000m"
      memory: "4Gi"

Next steps

• Getting Started — quick start walkthrough
• Installation — CLI installation and authentication