Configuration Reference¶

Complete reference for the .tinkero.yml configuration file used to control how your static sites are built and deployed.

Table of Contents¶

Overview
File Location
Field Reference
Complete Example
Common Configurations
Validation Rules
Error Examples
Migration Guide

Overview¶

The .tinkero.yml file controls how Tinkero builds and deploys your static site. Place it in the root of your repository.

Minimal Configuration¶

runtime: node
branch: main
outputDir: dist

With All Options¶

runtime: node
branch: main
outputDir: dist
nodeVersion: "20"
pythonVersion: "3.12"
buildCommand: npm run build
installCommand: npm ci
skipBuild: false
isSPA: false
env:
  NODE_ENV: production

File Location¶

The configuration file must be in your repository root with one of these names:

.tinkero.yml (preferred)
.tinkero.yaml (alternative)

your-repo/
├── .tinkero.yml    ← Configuration file
├── package.json    ← Node runtime
├── requirements.txt ← Python runtime (optional)
├── src/
└── ...

Field Reference¶

`runtime`¶

Type: string Required: No Default: node

Specifies which runtime to use for builds.

Allowed values: node, python

Examples:

runtime: node

runtime: python

`branch`¶

Type: string Required: No Default: main

Specifies which branch should trigger deployments.

Behavior	Description
Specified	Only pushes to this branch trigger builds
Omitted	Defaults to `main` branch
Empty string	Explicitly set to `""` to deploy from all branches

Examples:

# Only deploy from main branch
branch: main

# Only deploy from production branch
branch: production

# Deploy from feature branch
branch: feature/new-design

# Use default (main branch)
# branch: (not specified, defaults to main)

# Deploy from any branch (explicitly set empty string)
branch: ""

Branch Filtering Response:

When a push doesn't match the configured branch: - HTTP 200 OK is returned (webhook acknowledged) - Deployment is skipped - Response includes "skipped" status

`outputDir`¶

Type: string Required: No Default: dist

The directory containing your built static files. Must be relative to the repository root.

Framework	Typical Output Directory
Vite	`dist`
Create React App	`build`
Next.js (static export)	`out`
Gatsby	`public`
Vue CLI	`dist`
Angular	`dist/<project-name>`
Astro	`dist`
Hugo	`public`

Examples:

# Vite, Vue CLI (default)
outputDir: dist

# Create React App
outputDir: build

# Next.js static export
outputDir: out

# Nested output directory
outputDir: packages/web/dist

Security Restrictions:

Restriction	Invalid Example
Must be relative	`/var/www/html`
No path traversal	`../other-repo`
No absolute paths	`C:\build`

`nodeVersion`¶

Type: string Required: No Default: System default (current LTS)

Node.js version to use for building. Can be major version or exact version. Only used when runtime: node.

Examples:

# Use latest Node.js 20.x
nodeVersion: "20"

# Use latest Node.js 18.x
nodeVersion: "18"

# Use exact version
nodeVersion: "20.10.0"

# Use latest LTS (omit field)
# nodeVersion: (not specified)

Notes: - Always quote the version number ("20" not 20) - Supported versions depend on available Docker images - Use LTS versions for best stability

`pythonVersion`¶

Type: string Required: No Default: 3.12

Python version to use for building. Can be major version or exact version. Only used when runtime: python.

Examples:

# Use latest Python 3.12.x
pythonVersion: "3.12"

# Use exact version
pythonVersion: "3.11.7"

`skipBuild`¶

Type: boolean Required: No Default: false

Skip the build step entirely. Use when your repository contains pre-built static files.

Value	Behavior
`false`	Run install and build commands
`true`	Deploy `outputDir` contents directly

Examples:

# Pre-built files in repository
skipBuild: true
outputDir: public

# Standard build process (default)
skipBuild: false

When to Use: - Static HTML/CSS/JS sites without a build step - Pre-built files committed to the repository - Sites built by external CI/CD

Note: When skipBuild: true, the buildCommand and installCommand fields are ignored.

`buildCommand`¶

Type: string Required: No Default: npm run build (when runtime: node)

The command to run to build your static site. Only used when skipBuild is false. When runtime: python, this field is required unless skipBuild: true.

Examples:

# Standard npm build (default)
buildCommand: npm run build

# Production build script
buildCommand: npm run build:prod

# Yarn build
buildCommand: yarn build

# pnpm build
buildCommand: pnpm build

# Build with arguments
buildCommand: npm run build -- --mode production

# Multiple commands
buildCommand: npm run lint && npm run build

`installCommand`¶

Type: string Required: No Default: npm install (when runtime: node)

The command to install dependencies. Only used when skipBuild is false. When runtime: python, this field is required unless skipBuild: true.

Examples:

# Standard npm install (default)
installCommand: npm install

# npm ci (faster, more reliable for CI)
installCommand: npm ci

# Yarn
installCommand: yarn install

# Yarn (frozen lockfile)
installCommand: yarn install --frozen-lockfile

# pnpm
installCommand: pnpm install

# pnpm (frozen lockfile)
installCommand: pnpm install --frozen-lockfile

Recommendation: Use npm ci or yarn install --frozen-lockfile for reproducible builds.

`env`¶

Type: map[string]string Required: No Default: {}

Environment variables available during the build process. Available to both install and build commands.

Examples:

# Basic environment
env:
  NODE_ENV: production

# API configuration
env:
  NODE_ENV: production
  API_URL: https://api.example.com
  PUBLIC_URL: /

# Feature flags
env:
  NODE_ENV: production
  ENABLE_ANALYTICS: "true"
  ENABLE_DEBUG: "false"

# Framework-specific
env:
  # Create React App
  REACT_APP_API_URL: https://api.example.com
  PUBLIC_URL: /

  # Vite
  VITE_API_URL: https://api.example.com
  BASE_URL: /

Notes: - All values must be strings (quote booleans and numbers) - Variables are available during build only, not at runtime - Sensitive values should not be stored here

`isSPA`¶

Type: boolean Required: No Default: false

Enables Single Page Application (SPA) fallback routing. When enabled, requests for non-existent files will fall back to index.html, allowing client-side routers (React Router, Vue Router, etc.) to handle routing.

Value	Behavior
`false`	Standard static file serving (404 for missing files)
`true`	SPA fallback (missing files serve `index.html`)

Examples:

# Standard static site (default)
isSPA: false

# Single Page Application with client-side routing
isSPA: true

When to Use:

Enable isSPA: true when your application: - Uses client-side routing (React Router, Vue Router, Angular Router, etc.) - Has URLs like /dashboard, /users/123 that should be handled by JavaScript - Shows 404 errors when refreshing on client-side routes

Note: When isSPA: true, Caddy is configured to serve index.html for any request that doesn't match an existing file, allowing your JavaScript router to handle the URL.

Complete Example¶

# .tinkero.yml - Full configuration example

# Only deploy from main branch
branch: main

# Build output directory
outputDir: dist

# Node.js version
nodeVersion: "20"

# Skip build (default: false)
skipBuild: false

# Install command (runs before build)
installCommand: npm ci

# Build command
buildCommand: npm run build

# Enable SPA fallback routing (default: false)
# Set to true for React, Vue, Angular apps with client-side routing
isSPA: false

# Build environment variables
env:
  NODE_ENV: production
  API_URL: https://api.example.com
  ENABLE_ANALYTICS: "true"

Common Configurations¶

Create React App¶

runtime: node
branch: main
outputDir: build
nodeVersion: "20"
installCommand: npm ci
buildCommand: npm run build
isSPA: true  # Enable SPA fallback for React Router
env:
  REACT_APP_API_URL: https://api.example.com
  PUBLIC_URL: /

Vite¶

runtime: node
branch: main
outputDir: dist
nodeVersion: "20"
installCommand: npm ci
buildCommand: npm run build
isSPA: true  # Enable if using client-side routing
env:
  VITE_API_URL: https://api.example.com

Next.js Static Export¶

runtime: node
branch: main
outputDir: out
nodeVersion: "20"
installCommand: npm ci
buildCommand: npm run build

Note: Ensure your next.config.js has output: 'export'.

Vue CLI¶

runtime: node
branch: main
outputDir: dist
nodeVersion: "18"
installCommand: npm ci
buildCommand: npm run build
isSPA: true  # Enable SPA fallback for Vue Router
env:
  VUE_APP_API_URL: https://api.example.com

Angular¶

runtime: node
branch: main
outputDir: dist/my-app
nodeVersion: "18"
installCommand: npm ci
buildCommand: npm run build -- --configuration production
isSPA: true  # Enable SPA fallback for Angular Router

Gatsby¶

runtime: node
branch: main
outputDir: public
nodeVersion: "18"
installCommand: npm ci
buildCommand: npm run build
env:
  GATSBY_API_URL: https://api.example.com

Astro¶

runtime: node
branch: main
outputDir: dist
nodeVersion: "20"
installCommand: npm ci
buildCommand: npm run build

Hugo (with npm dependencies)¶

runtime: node
branch: main
outputDir: public
nodeVersion: "20"
installCommand: npm ci
buildCommand: npm run build

MkDocs (Python)¶

runtime: python
branch: main
outputDir: site
pythonVersion: "3.12"
installCommand: python -m pip install -r requirements.txt
buildCommand: mkdocs build

Pre-built Static Site¶

runtime: node
branch: main
outputDir: public
skipBuild: true

Monorepo (Specific Package)¶

runtime: node
branch: main
outputDir: packages/web/dist
installCommand: npm ci
buildCommand: npm run build --workspace=web

Validation Rules¶

The configuration is validated when loaded. Invalid configurations cause the deployment to fail.

`runtime` Validation¶

Rule	Valid	Invalid
Allowed values	`node`, `python`	`ruby`, `go`

`outputDir` Validation¶

Rule	Valid	Invalid
Relative path	`dist`, `build`, `packages/web/dist`	`/var/www`, `/home/user/dist`
No traversal	`dist`, `src/build`	`../other-repo`, `../../system`
Clean path	`dist/` becomes `dist`	N/A

`nodeVersion` Validation¶

Rule	Valid	Invalid
String format	`"20"`, `"18.16.0"`	`20` (unquoted number)
Supported versions	`"16"`, `"18"`, `"20"`	`"8"` (unsupported)

`pythonVersion` Validation¶

Rule	Valid	Invalid
String format	`"3.12"`, `"3.11.7"`	`3.12` (unquoted number)

`env` Validation¶

Rule	Valid	Invalid
String values	`"true"`, `"123"`	`true`, `123` (unquoted)
String keys	`NODE_ENV`, `API_URL`	`123` (numeric key)

Error Examples¶

Invalid Output Directory¶

Configuration:

outputDir: /etc/passwd

Error:

Error: outputDir must be a relative path, got absolute path: /etc/passwd

Solution:

outputDir: dist

Invalid Node Version Format¶

Configuration:

nodeVersion: 20

Error:

Error: nodeVersion must be a string, got integer

Solution:

nodeVersion: "20"

Invalid Environment Variable Value¶

Configuration:

env:
  ENABLE_DEBUG: true

Error:

Error: env values must be strings, got boolean for key ENABLE_DEBUG

Solution:

env:
  ENABLE_DEBUG: "true"

Missing Configuration File¶

Error:

Error: .tinkero.yml not found in repository root

Solution: Create .tinkero.yml in your repository root.

Invalid YAML Syntax¶

Configuration:

branch: main
outputDir dist  # Missing colon

Error:

Error: yaml: line 2: could not find expected ':'

Solution:

branch: main
outputDir: dist

Migration Guide¶

From Netlify (netlify.toml)¶

Netlify:

[build]
  publish = "dist"
  command = "npm run build"

[build.environment]
  NODE_VERSION = "18"
  NODE_ENV = "production"

Tinkero:

runtime: node
branch: main
outputDir: dist
nodeVersion: "18"
buildCommand: npm run build
installCommand: npm ci
env:
  NODE_ENV: production

From Vercel (vercel.json)¶

Vercel:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "vite"
}

Tinkero:

runtime: node
branch: main
outputDir: dist
buildCommand: npm run build
installCommand: npm ci

From GitHub Pages (workflow)¶

GitHub Actions:

- name: Build
  run: npm run build
  env:
    NODE_VERSION: 18

Tinkero:

runtime: node
branch: main
outputDir: dist
nodeVersion: "18"
buildCommand: npm run build
installCommand: npm ci

From Render (render.yaml)¶

Render:

services:
  - type: web
    name: my-app
    buildCommand: npm install && npm run build
    staticPublishPath: ./dist

Tinkero:

runtime: node
branch: main
outputDir: dist
installCommand: npm install
buildCommand: npm run build

See Also: - Examples - More configuration examples - Troubleshooting - Common configuration issues - FAQ - Frequently asked questions

Configuration Reference¶

Table of Contents¶

Overview¶

Minimal Configuration¶

With All Options¶

File Location¶

Field Reference¶

runtime¶

branch¶

outputDir¶

nodeVersion¶

pythonVersion¶

skipBuild¶

buildCommand¶

installCommand¶

env¶

isSPA¶

Complete Example¶

Common Configurations¶

Create React App¶

Vite¶

Next.js Static Export¶

Vue CLI¶

Angular¶

Gatsby¶

Astro¶

Hugo (with npm dependencies)¶

MkDocs (Python)¶

Pre-built Static Site¶

Monorepo (Specific Package)¶

Validation Rules¶

runtime Validation¶

outputDir Validation¶

nodeVersion Validation¶

pythonVersion Validation¶

env Validation¶

Error Examples¶

Invalid Output Directory¶

Invalid Node Version Format¶

Invalid Environment Variable Value¶

Missing Configuration File¶

Invalid YAML Syntax¶

Migration Guide¶

From Netlify (netlify.toml)¶

From Vercel (vercel.json)¶

From GitHub Pages (workflow)¶

From Render (render.yaml)¶

`runtime`¶

`branch`¶

`outputDir`¶

`nodeVersion`¶

`pythonVersion`¶

`skipBuild`¶

`buildCommand`¶

`installCommand`¶

`env`¶

`isSPA`¶

`runtime` Validation¶

`outputDir` Validation¶

`nodeVersion` Validation¶

`pythonVersion` Validation¶

`env` Validation¶