@maravilla-labs/vite-plugin

Vite plugin for Maravilla Runtime that enables platform services (KV, Database) during development while preserving the native framework development experience.

Installation

npm install -D @solutas/vite-plugin
# or
pnpm add -D @solutas/vite-plugin
# or
yarn add -D @solutas/vite-plugin

Setup

1. Start the Maravilla Dev Server

First, start the Maravilla dev server which provides platform services:

# Install the CLI globally
npm install -g @maravilla/cli

# Start the dev server (runs on port 3001 by default)
maravilla dev

2. Configure Vite

Add the plugin to your Vite configuration:

// vite.config.ts
import { defineConfig } from 'vite';
import { maravilla } from '@solutas/vite-plugin';

export default defineConfig({
  plugins: [
    maravilla({
      // Optional configuration
      devServerUrl: 'http://localhost:3001', // Default
      tenant: 'dev-tenant',                  // Default tenant ID
    }),
  ],
});

3. Use Platform Services

The plugin automatically configures the environment for @solutas/platform:

// Your application code
import { getPlatform } from '@solutas/platform';

const platform = getPlatform();

// Use KV store
await platform.env.KV.put('key', 'value');
const value = await platform.env.KV.get('key');

// Use database
const users = await platform.env.DB.find('users', {});

How It Works

Configures your Vite dev server so platform routes (auth pages, assets, realtime, API) work alongside your framework's dev server. With the plugin in place, your app uses plain relative URLs (/_auth/login, /api/kv) and they reach the platform server transparently.

graph LR
    A[Your App] --> B[Vite Dev Server]
    B --> C[vite-plugin-maravilla]
    C --> D[Sets Env Vars]
    D --> E[@solutas/platform]
    E --> F[Maravilla Dev Server]
    F --> G[Platform Services]

Configuration Options

devServerUrl

• Type: string
• Default: 'http://localhost:3001'
• Description: URL of the Maravilla dev server

tenant

• Type: string
• Default: 'dev-tenant'
• Description: Tenant ID for development (useful for multi-tenant testing)

additionalProxies

• Type: string[]
• Default: []
• Description: Extra URL prefixes to forward to the platform dev server, in addition to the built-in defaults. Use this if your app exposes custom routes the platform owns.

disableProxy

• Type: boolean
• Default: false
• Description: Opt out of the dev-server proxy. Useful if you route platform requests through some other mechanism.

Framework Examples

SvelteKit

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import { maravilla } from '@solutas/vite-plugin';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    sveltekit(),
    maravilla(),
  ],
});

Vue/Nuxt

// vite.config.ts
import vue from '@vitejs/plugin-vue';
import { maravilla } from '@solutas/vite-plugin';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    vue(),
    maravilla(),
  ],
});

React/Next.js

// vite.config.ts
import react from '@vitejs/plugin-react';
import { maravilla } from '@solutas/vite-plugin';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    react(),
    maravilla(),
  ],
});

Development Workflow

1. Terminal 1: Start Maravilla dev server

   maravilla dev

2. Terminal 2: Start your app dev server

   npm run dev  # or pnpm dev, yarn dev

3. Access Platform Services: Your app can now use KV, Database, and other platform services during development

Features

• ✅ Zero Configuration: Works out of the box with sensible defaults
• ✅ HMR Preserved: Maintains Vite's fast Hot Module Replacement
• ✅ Framework Agnostic: Works with any Vite-based framework
• ✅ SSR Support: Properly handles server-side rendering contexts
• ✅ TypeScript Support: Full type safety with @solutas/platform
• ✅ Development Parity: Same API in development and production

Troubleshooting

"Connection refused" error

Make sure the Maravilla dev server is running:

maravilla dev

Platform services not available

Check that both servers are running:

1. Maravilla dev server on port 3001
2. Your app dev server (usually port 5173)

Type errors with platform

Install the platform package:

npm install @solutas/platform

Environment Variables

The plugin sets these environment variables:

• MARAVILLA_DEV_SERVER: URL of the dev server
• MARAVILLA_TENANT: Tenant ID for development

You can also set these manually if needed:

MARAVILLA_DEV_SERVER=http://localhost:3001 npm run dev

Advanced Usage

Custom Tenant Configuration

Test multi-tenant scenarios by using different tenant IDs:

// vite.config.ts
export default defineConfig({
  plugins: [
    maravilla({
      tenant: process.env.TENANT_ID || 'dev-tenant',
    }),
  ],
});

TENANT_ID=customer-123 npm run dev

Multiple Dev Servers

Run multiple dev servers for different services:

// vite.config.ts
export default defineConfig({
  plugins: [
    maravilla({
      devServerUrl: process.env.PLATFORM_URL || 'http://localhost:3001',
    }),
  ],
});

Related Packages

• @solutas/platform - Platform client library
• @solutas/adapter-sveltekit - SvelteKit adapter
• @solutas/cli - Command-line interface

License

Proprietary. © 2025 SOLUTAS GmbH, Switzerland. All rights reserved. Use is governed by the root LICENSE file or a separate written agreement with SOLUTAS GmbH.