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)
Health checks: Provides endpoint status and diagnostics

If you're working on serving release artifacts, you'll be working in this app.

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:8080 by default. In development, it reads CSS directly from the style app's dist/ folder for instant feedback.

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

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:
- themes.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
```
Formatting:
```
pnpm --filter @repo/api format
```
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 any Nitro or app-specific environment 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

Integration with other apps

Style app: API serves the built CSS bundles from releases

Release routes

Health routes

On this page