API

Introduction

The API app is a Nitro server that provides backend services for Coolify Tweaks:

Release asset proxying: Serves GitHub release assets (CSS bundles, source maps)
CSS bundle serving: Delivers published stylesheets to users
Health checks: Provides endpoint status and diagnostics
Analytics: Tracks usage and diagnostics when configured with a database

If you're working on how users fetch styles programmatically, tracking usage, or serving release artifacts, you'll be working in this app.

packages/db contains the Drizzle ORM schema and Neon database helpers that power analytics routes and other database-backed features.

File layout

config.tsApp configuration

nitro.config.tsNitro configuration

package.json

Local workflow

Start the dev server:

pnpm --filter @repo/api dev

The API runs on http://localhost:3001 by default.

Edit routes under apps/api/src/routes/ or utility functions in apps/api/src/utils/.

Database changes: When you add analytics tables or modify schema definitions:

pnpm db:push

This syncs the Drizzle schema to your local Postgres/Neon database.

Environment variables: Configure via .env in the repo root:

POSTGRES_URL - Required for analytics routes
Other Nitro-specific variables as needed

Concepts

Theme injection

The API supports dynamic theme injection for main.user.css requests. Here's how it works:

Build-time markers: The Style app's PostCSS plugin (theme-identifier.ts) injects special comment markers around CSS variable definitions:

/* ==UI-THEME-VARS:START== */
:root {
  --background: #fdfdfd;
  --foreground: #000;
  /* ... more variables ... */
}
.dark {
  --background: #1f1c23;
  /* ... more variables ... */
}
/* ==UI-THEME-VARS:END== */

Theme request flow: When a user requests CSS with ?theme=<theme-id>:
- The API fetches the base CSS from GitHub releases
- Fetches theme data from TweakCN (shadcn registry) using the theme ID
- Converts the theme's CSS variables to CSS using cssVarsToCss() (creates :root and .dark selectors)
- Transforms the CSS using Lightning CSS for browser compatibility
- Uses regex to find and replace the content between UI-THEME-VARS markers
- Updates the updateURL in the userstyle metadata to preserve the theme parameter
Implementation: The theme injection logic spans multiple utility files:
- stylus.ts: getThemeCss() fetches and validates theme data from TweakCN, processContent() handles the find-and-replace operation
- css-transformer.ts: cssVarsToCss() converts theme variables to CSS format
- css-compiler.ts: transformCss() applies Lightning CSS transformations for browser compatibility

This allows users to install themed versions of the stylesheet while maintaining the same update mechanism.

Routes

For more details about API usage, visit /docs/api.

Testing

Run these commands from the repo root:

Linting:
```
pnpm --filter @repo/api lint
```
Type checking:
```
pnpm --filter @repo/api typecheck
```
Spell checking:
```
pnpm --filter @repo/api check:spelling
```

Deployment

Vercel

Create a new Vercel project.
Set the root directory to apps/api.
Vercel automatically detects Nitro and configures the build output.
Configure environment variables:
- POSTGRES_URL - Required for analytics features
- Any other Nitro or app-specific variables
Deploy. Once live, the API will:
- Serve release assets from GitHub releases
- Proxy CSS bundles generated by the Style app
- Respond to health check requests
- Handle analytics tracking (if configured)

Integration with other apps

Style app: API serves the built CSS bundles from releases
Database: Uses @repo/db for analytics and data persistence

Release routes

Health routes

Analytics routes

On this page