Introduction
Quick Start
Get a Telaio app running from scratch in a few minutes.
Quick Start
Prerequisites
- Node.js >= 20
- pnpm
- Your project must have
"type": "module"inpackage.json
Option A: Scaffold with the CLI
pnpx telaio init my-app
cd my-app
pnpm installThe init command creates the project structure, installs dependencies, and sets up configuration. Skip ahead to First Route.
Option B: Manual Install
Install the core package:
pnpm add telaioInstall peer dependencies for the features you need:
| Feature | Peer Dependencies |
|---|---|
| Database | pg kysely |
| Cache | redis |
| Queue | pg-boss |
| Auth (better-auth) | better-auth |
@aws-sdk/client-ses @react-email/components | |
| S3 | @aws-sdk/client-s3 |
| Dev pretty logs | pino-pretty |
| Multipart uploads | @fastify/multipart |
| CORS | @fastify/cors |
| Swagger / API docs | @fastify/swagger @scalar/fastify-api-reference |
Minimal Wiring
Create src/app.ts:
import { loadConfig, createApp } from 'telaio';
const config = loadConfig({
modules: { server: true, database: true, cache: true },
});
export const app = await createApp({ config })
.withDatabase()
.withCache()
.withPlugins({ cors: true })
.build();Create src/server.ts:
import { app } from './app.js';
await app.start();node --import tsx/esm src/server.tsFirst Route
Add src/routes/users.ts:
import { Type } from 'typebox';
import type { FastifyPluginAsync } from 'fastify';
const UserSchema = Type.Object(
{
id: Type.String(),
name: Type.String(),
},
{ $id: 'User' },
);
const plugin: FastifyPluginAsync = async (fastify) => {
fastify.get(
'/users/:id',
{
schema: {
params: Type.Object({ id: Type.String() }),
response: { 200: UserSchema },
},
},
async (req) => {
return { id: req.params.id, name: 'Alice' };
},
);
};
export default plugin;Telaio's autoload discovers src/routes/** automatically.
Add API Documentation
Tack on Swagger + Scalar UI:
const app = await createApp({ config })
.withDatabase()
.withCache()
.withSwagger({ info: { title: 'My API', version: '1.0.0' } })
.withApiDocs()
.build();Start the server and visit http://localhost:4001/docs for the interactive API explorer.