Installation

System Requirements

Before installing Lithia, make sure you have:

• Node.js 20.0 or later
• npm, pnpm, or yarn package manager
• A code editor (VS Code recommended)

Create a New Project

The fastest way to create a new Lithia project is using create-lithia-app:

npx create-lithia-app@latest

This command will show an interactive prompt to help you create a new project in few steps.

Manual Installation

If you prefer to set up Lithia manually in an existing project:

# Create project directory
mkdir my-lithia-api
cd my-lithia-api

# Initialize package.json
npm init -y

# Install Lithia
npm install lithia@latest

# Install TypeScript (required)
npm install -D typescript @types/node

Create Project Structure

mkdir -p src/routes

Add TypeScript Configuration

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "node",
    "allowJs": false,
    "types": ["node"],
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "strict": true,
    "baseUrl": "",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "exclude": ["node_modules", ".lithia"]
}

Add npm Scripts

Update your package.json:

{
  "scripts": {
    "dev": "lithia dev",
    "build": "lithia build",
    "start": "lithia start"
  }
}

Create the Configuration File

Create lithia.config.ts:

import { defineLithiaConfig } from 'lithia';

export default defineLithiaConfig({
  server: {
    port: 3000,
  },
  studio: {
    enabled: true,
  }
});

Lithia does not have a entry point file like a traditional server, and we don't want you lose time writing one, so we provide a lithia.config.ts file for you to configure how the server should run. Check out the configuration for more details.

Create Your First Route

Create a test route to verify everything works:

import type { LithiaRequest, LithiaResponse } from 'lithia';

export default async (_req: LithiaRequest, res: LithiaResponse) => {
  return res.json({ 
    message: "Hello from Lithia!",
    timestamp: new Date().toISOString()
  });
};

Project Structure

After installation, your project will have this structure:

my-lithia-api/
├── src/
│   └── routes/
│      └── hello/
│          └── route.get.ts
├── lithia.config.ts
├── package.json
└── tsconfig.json

See more at Project Structure to understand how your project structure becomes your API automatically.

Start Development Server

Run the development server:

pnpm run dev

You should see:

▲ Server listening on http://localhost:3000
▲ Studio listening on http://localhost:8473

Test Your API

Open your browser or use curl:

curl http://localhost:3000/hello

Expected response:

{
  "message": "Hello from Lithia!",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Access Lithia Studio

Open your browser at http://localhost:8473.

You'll see the Lithia Studio dashboard with:

• Server metrics and uptime
• Your routes list
• Live logs
• Route testing interface

Troubleshooting

Port already in use

If port 3000 is already in use, you can change it on your lithia.config.ts file:

import { defineLithiaConfig } from 'lithia';

export default defineLithiaConfig({
  server: {
    port: 4000  // Change API port
  },
});

But if 8473 is already in use you'll have a problem... the Studio always runs on port 8473 and you can't change it. Why 8473? Because no one else uses it :)

If somehow it's taken on your machine, you'll need to kill whatever is using it.

TypeScript Errors

You can type-check your code by running:

tsc --noEmit

Cannot Import Route Module

Usually, it can only happen when you make a request to a route when using "type": "module" in your package.json.

To solve it, it's simple, just remove it, you don't need it.