Quick Start

Project type: Select Vite or Godot (for this quickstart, select Vite)
Framework: Choose React, Vue, Svelte, or Vanilla (for this quickstart, select React)
Project info: Name, description, and emoji
Integrations: Timeback, Database, etc.

Create a Provider

Create a context provider to make the Playcademy client available throughout your app:

src/PlaycademyProvider.tsx

import { createContext, useContext, useEffect, useState } from 'react'

import { PlaycademyClient } from '@playcademy/sdk'

const PlaycademyContext = createContext<PlaycademyClient | null>(null)

export function PlaycademyProvider({ children }: { children: React.ReactNode }) {
    const [client, setClient] = useState<PlaycademyClient | null>(null)

    useEffect(() => {
        PlaycademyClient.init().then(setClient)
    }, [])

    if (!client) return <div>Loading...</div>

    return <PlaycademyContext.Provider value={client}>{children}</PlaycademyContext.Provider>
}

export function usePlaycademy() {
    const client = useContext(PlaycademyContext)
    if (!client) throw new Error('usePlaycademy must be used within PlaycademyProvider')
    return client
}

Wrap Your App

Update your app entry point to wrap everything with the provider:

src/main.tsx

import React from 'react'
import ReactDOM from 'react-dom/client'

import App from './App'
import { PlaycademyProvider } from './PlaycademyProvider'

import './index.css'

ReactDOM.createRoot(document.getElementById('root')!).render(
    <React.StrictMode>
        <PlaycademyProvider>
            <App />
        </PlaycademyProvider>
    </React.StrictMode>,
)

Coming Soon

Framework-specific tooling is coming soon.

src/main.ts

import { PlaycademyProvider } from '@playcademy/react'

ReactDOM.createRoot(document.getElementById('root')!).render(
    <React.StrictMode>
        <PlaycademyProvider>
            <App />
        </PlaycademyProvider>
    </React.StrictMode>,
)

Use the Client

Now use the client anywhere in your app:

src/App.tsx

import { useEffect, useState } from 'react'

import { usePlaycademy } from './PlaycademyProvider'

function App() {
    const client = usePlaycademy()
    const [user, setUser] = useState<{ name: string; id: string } | null>(null)

    useEffect(() => {
        client.users.me().then(setUser)
    }, [client])

    if (!user) return <div>Loading user...</div>

    return (
        <div>
            <h1>Welcome, {user.name}!</h1>
            <p>Your project is connected to Playcademy! 🎉</p>
            <p>User ID: {user.id}</p>
        </div>
    )
}

export default App

Using a different framework?

The pattern is the same.

Initialize PlaycademyClient.init() early in your app, then use the client throughout your components.

Develop Locally

Start the Vite development server:

bun dev

npm run dev

pnpm run dev

yarn run dev

The Vite Plugin automatically:

Starts the sandbox server (localhost:4321): simulates the platform API
Starts the backend server (localhost:8788): runs your custom routes and integrations

Not Using Vite?

If you're not using Vite, start the backend server separately:

Command

$ playcademy dev

Then start your own bundler/dev server in another terminal.

Build Your Project

Build your project for deployment:

bun run build

npm run build

pnpm run build

yarn run build

The Vite Plugin automatically creates .playcademy/<app-slug>.zip ready for deployment.

Optional: Add buildPath to Config

You can add the build path to your config to skip the prompt during deployment:

playcademy.config.js

export default {
    name: 'Playcademy App',
    description: 'A fun project',
    emoji: '🚀',
    buildPath: '.playcademy/playcademy-app.zip',
}

If you don't add it, playcademy deploy will prompt you for the path interactively.

Deploy to Playcademy

Deploy your project with a single command:

Command

$ playcademy deploy

Deploy to Production

The CLI deploys to staging by default.

When you're ready to go live:

Command

$ playcademy deploy --env production

Stream Logs

Debug your deployed app by streaming real-time logs:

Command

$ playcademy logs

See playcademy logs for all options.

Next Steps

You've built and deployed your first (very simple) Playcademy app!

Ask a Question

Ready to build a production-ready app?

Explore backend integrations that add storage, user accounts, and server-side logic.

Integration	Description
Database	Type-safe SQLite with Drizzle ORM
Authentication	User accounts with Better Auth
Custom Routes	Server-side API endpoints
KV Storage	Fast key-value storage
Bucket Storage	File storage for assets
Timeback	Educational progress tracking

Integrations

Add backend features to unlock the full platform capabilities

SDK Documentation

Deep dive into all available platform APIs

Development Guide

Learn advanced local development workflows and debugging

CLI Reference

Master all CLI commands for development and deployment

Integrations

SDK Documentation

Development Guide

CLI Reference

On this page