@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

The vite plugin performs two key functions:

1. Environment Configuration: Sets environment variables that @solutas/platform uses to connect to the dev server
2. SSR Context Management: Ensures platform instances are properly managed during server-side rendering

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)

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.