Vite Plugin

Overview

The @playcademy/vite-plugin provides a streamlined local dev setup + build preparation for Vite-based projects.

Vite plugin architecture showing development stack

The plugin works out of the box for most projects.

Just add it to your vite.config.ts file and run vite dev to get started.

Installation

Automatic Setup

If you have an existing Playcademy project with playcademy.config.{js,json}:

Command

$ playcademy vite config

This will:

Install @playcademy/vite-plugin
Update or create vite.config.ts
Add the plugin to your configuration

Manual Setup

bun add -D @playcademy/vite-plugin

npm install -D @playcademy/vite-plugin

pnpm add -D @playcademy/vite-plugin

yarn add -D @playcademy/vite-plugin

vite.config.ts

import { defineConfig } from 'vite'

import { playcademy } from '@playcademy/vite-plugin'

export default defineConfig({
    plugins: [playcademy()],
})

That's it. Run your dev command and the plugin handles the rest.

Configuration

Plugin Mode

When deploying to Playcademy, you'll be given two URLs: a platform link and a standalone link.

Platform vs. Standalone

Configuring the plugin's mode option lets you develop against your chosen scenario:

Platform mode simulates being launched inside the Playcademy platform
Standalone mode simulates direct access without platform integration

Switch between modes with the m + enter hotkey.

vite.config.ts

playcademy({
    mode: 'platform',
})

Option	Type	Default	Description
`mode`	`'platform' \| 'standalone'`	`'platform'`	Plugin operation mode

Export Options

Control build output:

vite.config.ts

playcademy({
    export: {
        autoZip: true,
    },
})

Option	Type	Default	Description
`autoZip`	`boolean`	`true`	Create deployment zip archive

Sandbox Options

Configure the local development sandbox:

vite.config.ts

playcademy({
    sandbox: {
        autoStart: true,
        recreateDb: false,
        seed: true,
        memoryOnly: false,
        databasePath: undefined,
    },
})

Option	Type	Default	Description
`autoStart`	`boolean`	`true`	Auto-start sandbox with dev server
`url`	`string`	`undefined`	Custom sandbox URL (disables autoStart)
`verbose`	`boolean`	`false`	Enable verbose logging
`logLevel`	`string`	`'info'`	Log level: `debug`, `info`, `warn`, `error`
`recreateDb`	`boolean`	`false`	Recreate database on each start
`seed`	`boolean`	`true`	Seed database with demo data
`memoryOnly`	`boolean`	`false`	Use in-memory database (non-persistent)
`databasePath`	`string`	`undefined`	Custom database file path

Display Options

Configure visual elements during development:

vite.config.ts

playcademy({
    display: {
        hideBadge: true,
    },
})

Option	Type	Default	Description
`hideBadge`	`boolean`	`false`	Hide Playcademy corner badge

Timeback Options

All courses from your playcademy.config.js are automatically enrolled with mock data.

You can override defaults for testing purposes:

vite.config.ts

playcademy({
    timeback: {
        id: '...',
        role: 'teacher',
        organization: { id: '...', name: '...', type: 'school' },
        courses: { 'FastMath:3': '...' },
    },
})

Option	Type	Default	Description
`id`	`string`	auto-mock	Real student sourcedId for live testing
`role`	`string`	`'student'`	`student`, `parent`, `teacher`, `administrator`, or `guardian`
`organization`	`object`	`'mock'`	Custom org with `id`, `name`, `type`
`courses`	`object`	auto-enroll	Map of course keys to `'mock'`, real sourcedId, or `null`

Hotkeys

Press t in the terminal to cycle through roles during development.

Read more about local development with Timeback.

Common Configurations

Standalone Mode

vite.config.ts

playcademy({
    mode: 'standalone',
})

Disable Auto-Zip

Auto-zip is enabled by default. To disable:

vite.config.ts

playcademy({
    export: {
        autoZip: false,
    },
})

Hide Playcademy Badge

vite.config.ts

playcademy({
    display: {
        hideBadge: true,
    },
})

Reset Sandbox Data on Launch

Useful for testing fresh database states:

vite.config.ts

playcademy({
    sandbox: {
        recreateDb: true,
    },
})

In-Memory Database

Use RAM-based database in ephemeral contexts:

vite.config.ts

playcademy({
    sandbox: {
        memoryOnly: true,
    },
})

Custom Database Path

Specify a custom location for the database file:

vite.config.ts

playcademy({
    sandbox: {
        databasePath: './dev-sandbox.db',
    },
})

What's Next?

Development Guide

Learn about the local sandbox, hotkeys, and Timeback testing.

Build Guide

Understand manifest generation and deployment preparation.

SDK Introduction

Start using the SDK in your project to access platform features.

Quick Start

Build your first project with the Vite plugin from scratch.

Development Guide

Build Guide

SDK Introduction

Quick Start

On this page