@maravilla-labs/adapter-sveltekit

SvelteKit adapter for Maravilla Runtime - deploy your SvelteKit applications to the edge with built-in KV, Database, and platform services.

Installation

npm install -D @solutas/adapter-sveltekit
# or
pnpm add -D @solutas/adapter-sveltekit
# or
yarn add -D @solutas/adapter-sveltekit

Also install the platform client and Vite plugin:

pnpm add @maravilla/platform
pnpm add -D @solutas/vite-plugin

Setup

1. Configure the Adapter

Update your svelte.config.js:

import adapter from '@solutas/adapter-sveltekit';

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

export default config;

2. Enable the Vite plugin

Add @solutas/vite-plugin in vite.config.ts to wire the dev server and inject the platform during development:

import { defineConfig } from 'vite';
import { sveltekit } from '@sveltejs/kit/vite';
import { maravilla, maravillaFunctions } from '@solutas/vite-plugin';

export default defineConfig({
  plugins: [
    sveltekit(),
    maravilla({
      devServerUrl: 'http://localhost:3001',
      tenant: 'demo-tenant'
    }),
    // Optional: hot-reload local edge functions
    maravillaFunctions({
      functionsDir: './functions',
      watch: true
    })
  ]
});

3. Use Platform Services

Use the platform client in your SvelteKit routes:

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

export const load: PageServerLoad = async () => {
  const platform = getPlatform();
  
  // Use KV store
  // Namespaced example from the demo
  const cachedData = await platform.env.KV.demo.get('homepage:data');
  
  // Use database
  const users = await platform.env.DB.find('users', { active: true });
  
  return {
    data: cachedData ?? null,
    users,
  };
};

Development Workflow

1. Install Dependencies

pnpm install

2. Development Mode

Pick one of the flows below.

Option A — All-in-one (CLI orchestrates platform and Vite):

maravilla dev

Option B — Manual (start platform and Vite separately):

pnpm dev:platform   # starts platform dev server on :3001 (see demo package.json)
pnpm dev

Your app will run on http://localhost:5173 with platform services proxied to http://localhost:3001.

3. Production Build

# Build the application
pnpm build

# Preview the production build
maravilla preview .maravilla

This creates a .maravilla/ directory with:

• manifest.json - Platform configuration
• server.js - Server-side application bundle
• server.js.map - Source maps
• static/ - Pre-rendered pages and static assets

Build Output

The adapter generates an optimized bundle structure:

.maravilla/
├── manifest.json      # Platform configuration (runtime v2)
├── server.js          # Main server bundle
├── server.js.map      # Source maps
└── static/            # Static assets + prerendered pages
    ├── _app/            # Client-side JS/CSS
    ├── favicon.svg
    └── index.html       # Pre-rendered pages

Manifest Configuration

The generated manifest.json (v2) includes:

{
  "version": 2,
  "runtime": "maravilla",
  "entrypoint": "server.js",
  "static": "static",
  "routing": {
    "prerendered": ["/index.html"],
    "assets": ["/_app/...", "/favicon.svg", "/robots.txt"],
    "dynamic": { "api": "/api/*", "serverRoutes": "/*" }
  },
  "routes": { "include": ["/*"], "exclude": [] },
  "env": { "prefix": "PUBLIC_" },
  "features": { "ssr": true, "polyfill": true, "compression": false }
}

Platform Services

KV Store

Perfect for caching, session storage, and simple key-value data (demo-style namespace shown):

// src/routes/api/cache/+server.ts
import { getPlatform } from '@maravilla/platform';
import { json } from '@sveltejs/kit';

export async function GET({ params }) {
  const platform = getPlatform();
  const value = await platform.env.KV.demo.get(`cache:${params.key}`);
  
  return json({ value });
}

export async function PUT({ params, request }) {
  const platform = getPlatform();
  const data = await request.json();
  
  await platform.env.KV.demo.put(
    `cache:${params.key}`,
    data,
    { expirationTtl: 3600 } // 1 hour TTL
  );
  
  return json({ success: true });
}

Database (MongoDB-style)

Document database with rich query capabilities:

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

export const load: PageServerLoad = async () => {
  const platform = getPlatform();
  
  const users = await platform.env.DB.find('users', {
    active: true,
  }, {
    sort: { createdAt: -1 },
    limit: 20,
  });
  
  return { users };
};

export const actions: Actions = {
  create: async ({ request }) => {
    const platform = getPlatform();
    const formData = await request.formData();
    
    const result = await platform.env.DB.insertOne('users', {
      name: formData.get('name'),
      email: formData.get('email'),
      active: true,
      createdAt: new Date(),
    });
    
    return { success: true, id: result.insertedId };
  },
  
  toggle: async ({ request }) => {
    const platform = getPlatform();
    const formData = await request.formData();
    const userId = formData.get('id');
    
    await platform.env.DB.updateOne('users',
      { _id: userId },
      { $set: { active: formData.get('active') === 'true' } }
    );
    
    return { success: true };
  },
};

Environment Variables

The adapter respects these environment variables:

• MARAVILLA_ENV - Set to 'production' for production builds
• MARAVILLA_DEV_SERVER - Dev server URL (development only)
• MARAVILLA_TENANT - Tenant ID (development only)

TypeScript Support

Add global platform types to your app:

// app.d.ts
import type { KVNamespace, Database } from '@maravilla/platform';

declare global {
  namespace App {
    interface Platform {
      env: {
        KV: KVNamespace;
        DB: Database;
      };
    }
  }
}

export {};

Configuration Options

out

• Type: string
• Default: '.maravilla'
• Description: Output directory for the build

precompress

• Type: boolean
• Default: false
• Description: Pre-compress static assets with gzip/brotli

polyfill

• Type: boolean
• Default: true
• Description: Include runtime polyfills for compatibility

envPrefix

• Type: string
• Default: 'PUBLIC_'
• Description: Prefix for environment variables to expose to the client

include / exclude

• Type: string[]
• Default: include: ['/*'], exclude: []
• Description: Route include/exclude patterns recorded in the manifest

external

• Type: string[]
• Default: []
• Description: Extra dependencies to exclude from the server bundle (esbuild external)

Example Application

Check out the demo application in examples/demo/:

cd packages/adapter-sveltekit/examples/demo
pnpm install
pnpm dev

The demo includes:

• KV Playground (/kv) - Interactive KV store operations
• Users Directory (/users) - Full CRUD with MongoDB-style database
• Sverdle Game (/sverdle) - Wordle clone demonstrating SSR
• About Page (/about) - Static page example

Edge Functions (optional)

Place functions in a top-level functions/ folder. The adapter will build and integrate them into .maravilla/manifest.json during pnpm build. For dev HMR, add the maravillaFunctions() plugin as shown above.

Deployment

Local Preview

# Build your app
pnpm build

# Preview with Maravilla runtime
maravilla preview .maravilla

Production Deployment

# Build for production
NODE_ENV=production pnpm build

# Deploy (coming soon)
maravilla deploy .maravilla

Performance

The adapter optimizes for edge deployment:

• Code Splitting: Automatic chunking for optimal loading
• Tree Shaking: Removes unused code
• Minification: Compressed JavaScript output
• Static Optimization: Pre-rendered pages served from CDN
• Asset Compression: Brotli/gzip pre-compression

Troubleshooting

Build Errors

If you encounter build errors:

1. Clear the build cache:

   rm -rf .svelte-kit .maravilla

2. Reinstall dependencies:

   pnpm install

3. Rebuild:

   pnpm build

Platform Services Not Available

Ensure the dev server is running:

maravilla dev

Type Errors

Install type definitions:

pnpm add @maravilla/platform

Migration from Other Adapters

From @sveltejs/adapter-node

1. Replace the adapter import
2. Remove Node.js-specific code
3. Replace database calls with platform.env.DB
4. Replace Redis/cache with platform.env.KV

From @sveltejs/adapter-vercel

1. Replace the adapter import
2. Update environment variable access
3. Replace Vercel KV with platform.env.KV
4. Update API routes to use platform services

Related Packages

• @maravilla/platform - Platform client library
• @solutas/vite-plugin - Vite plugin for development
• @solutas/cli - Command-line interface

License

Proprietary. Copyright © 2025 SOLUTAS GmbH, Switzerland. All rights reserved. Use is subject to the terms in the root LICENSE file or a separate written agreement with SOLUTAS GmbH.