Development
Run your backend locally with hot reload
Overview
The playcademy dev command starts a local backend development server that serves your API routes.
It includes routes for integrations — like Timeback — out of the box.
Using Vite?
The @playcademy/vite-plugin package automatically starts playcademy dev for you when you run
bun dev.
It is highly recommended to use the Vite Plugin instead of the CLI dev server.
Starting the Dev Server
$ playcademy dev✔ Project API started: http://localhost:8788/api/health GET/api/hello GET, POST✦ Press ctrl+c to stopLocal Development
When you run playcademy dev, you get a couple of built-in utility routes:
| Endpoint | Purpose |
|---|---|
http://localhost:8788/api | API route index |
http://localhost:8788/health | Health check |
In addition, the server automatically discovers and registers:
- Custom routes: Any routes in your
server/api/directory - Integration routes: Timeback (+ more to come)
Custom API Routes
The dev server automatically discovers and serves routes from your server/api/ directory.
Routes are simple TypeScript files that export HTTP method handlers:
export async function GET(c: Context) {
return c.json({ message: 'Hello from backend!' })
}Learn More
See the Custom Routes Guide for complete documentation on creating and structuring routes.
Hot Reloading
The dev server automatically reloads when you:
- Add new routes: Creates new endpoints
- Modify existing routes: Updates handler logic
- Update config: Reloads integrations
No Manual Restart
Hot reload is enabled by default and watches for file changes automatically
What triggers a reload:
| Change | Result |
|---|---|
Add server/api/new-route.ts | Route registered automatically |
Edit server/api/existing.ts | Route handler updated |
Update playcademy.config.js | Config reloaded, integrations updated |
What doesn't trigger a reload:
- Changes to frontend code (typically handled by your frontend framework)
- Changes to
node_modules - Changes outside the project directory
Server Options
Customize the dev server behavior:
$ playcademy dev --port 9000$ playcademy dev --no-reload$ playcademy dev --no-logger| Option | Default | Description |
|---|---|---|
-p, --port | 8788 | Backend server port |
--no-reload | (enabled) | Disable hot module replacement |
--no-logger | (enabled) | Disable HTTP request logging |
Integrations in Development
Timeback Integration
Timeback Disabled (locally)
Timeback routes are disabled in local development.
This is temporary until a local Timeback environment is available.
Calls to Timeback endpoints return 503 with a helpful error message.
How to test out your Timeback integration:
- Deploy your project to staging with
playcademy deploy --env staging - Mock Timeback calls in your frontend code
Debugging
Request Logging
By default, all HTTP requests are logged to the console:
GET /api/hello 200 OK (12ms)
POST /api/validate-answer 200 OK (5ms)Disable with --no-logger:
$ playcademy dev --no-loggerInspecting Routes
The dev server displays all registered routes on startup:
/health GET
/api/hello GET, POST
/api/validate-answer POST
/api/users/:userId GETWhat's Next?
Command Reference
Review every CLI command, option, and integration flag.
Deployment Guide
Learn how to ship the code you just tested locally.
Custom Routes Guide
Go deeper on structuring API handlers and backend logic.
Timeback Integration
See how curriculum-aligned data flows through your backend routes.