Hosting on Vercel

TinyJS sites deploy to Vercel as static output. Vercel installs the project dependencies, runs the TinyJS build, and serves the contents of dist/.

Add the Vercel configuration

Add vercel.json at the project root:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}

The build command uses the existing build script in package.json:

{
  "scripts": {
    "build": "tinyjs build"
  },
  "engines": {
    "node": ">=22"
  }
}

Vercel supports project-level buildCommand and outputDirectory settings in vercel.json. Only the contents of the configured output directory are served. See Vercel's build configuration documentation.

Deploy from Git

1. Push the project to GitHub, GitLab, or Bitbucket.
2. Create a new Vercel project and import the repository.
3. Leave the project root unchanged unless the TinyJS site lives inside a monorepo.
4. Deploy.

The committed vercel.json supplies the build and output settings. Vercel creates a new deployment when changes are pushed to a connected branch.

Deploy from the command line

From the project root, create a preview deployment:

npx vercel

When the preview is ready, deploy to production:

npx vercel --prod

See Vercel's CLI deployment guide for authentication and project-linking options.

Routes and the 404 page

TinyJS writes each route as static HTML under dist/. It also emits dist/404.html, which Vercel automatically uses when no static route matches.

Route-specific status and header metadata stored in dist/tinyjs.json is not automatically applied by static hosting. Translate any custom redirects or headers into vercel.json using Vercel's project configuration.

The dynamic tinyjs serve command is for local preview or a long-running Node.js server. Use tinyjs build for this Vercel setup.

Optional PostHog analytics

This example includes optional PostHog page and interaction tracking. Add both variables in the Vercel project settings, using the project token and host shown in your PostHog project settings:

POSTHOG_PROJECT_TOKEN=phc_...
POSTHOG_HOST=https://us.i.posthog.com

Use the host for your own PostHog region or self-hosted instance. The project token is the public token intended for browser tracking; do not use a personal API key.

Tracking is build-time opt-in. If both variables are available, TinyJS adds PostHog's browser snippet to every page. If either variable—or the entire .env file—is absent, the snippet is omitted and the site still builds and runs normally.

Vercel supplies configured environment variables to the build automatically. For a local one-off build, export the values in your shell before running npm run build. See PostHog's JavaScript setup guide for the current browser SDK configuration.