Project Configuration

Perry projects use perry.toml and package.json for configuration. No special config file is required for basic usage, but larger projects benefit from Perry-specific settings.

Looking for the full perry.toml reference? See perry.toml Reference for every field, section, platform option, and environment variable.

Basic Setup

perry init my-project
cd my-project

This creates a package.json and a starter src/index.ts.

package.json

{
  "name": "my-project",
  "version": "1.0.0",
  "main": "src/index.ts",
  "perry": {
    "compilePackages": []
  }
}

Perry Configuration

The perry field in package.json controls compiler behavior:

compilePackages

List npm packages to compile natively instead of routing through the JavaScript runtime:

{
  "perry": {
    "compilePackages": ["@noble/curves", "@noble/hashes"]
  }
}

When a package is listed here, Perry:

1. Resolves the package in node_modules/
2. Prefers TypeScript source (src/index.ts) over compiled JavaScript (lib/index.js)
3. Compiles all functions natively through LLVM
4. Deduplicates across nested node_modules/ to prevent duplicate linker symbols

This is useful for pure TypeScript/JavaScript packages that don’t rely on Node.js APIs. Packages that use native bindings, eval(), or dynamic require() won’t work.

codegen

Perry is an ahead-of-time compiler: it never runs a code string at runtime. Many libraries that would normally JIT a function from a schema or a config (ajv, fast-json-stringify, Prisma, Drizzle, …) ship a build-time mode that emits plain, eval-free source instead. The codegen field declares the commands that produce that source. Perry runs them before compiling, then compiles the generated output natively — so the shipped binary links no JavaScript engine.

{
  "perry": {
    "codegen": [
      { "label": "ajv validators", "command": "node scripts/generate-validators.mjs" }
    ]
  }
}

Each entry is either a bare command string or an object with command (required) and an optional label shown in build output. Commands run in declaration order, with the working directory set to the folder containing this package.json, so relative script paths resolve as expected. If a command exits non-zero the build fails and prints its captured stdout/stderr.

Security: codegen is read only from the host project’s package.json — never from a dependency’s — so a transitive dependency can’t smuggle in a build command (the same trust boundary as compilePackages). Skip the steps for a reproducible or sandboxed build (where the generated output is already committed) with perry compile --no-codegen or PERRY_SKIP_CODEGEN=1.

Worked example: ajv/standalone

ajv validates against a JSON Schema. Its default mode JITs the validator with new Function; its standalone mode emits the same validator as plain source. The generator script:

// scripts/generate-validators.mjs
import Ajv from "ajv";
import standaloneCode from "ajv/dist/standalone/index.js";
import { writeFileSync } from "node:fs";

const schema = {
  $id: "Config",
  type: "object",
  properties: { host: {}, port: {} },
  required: ["host", "port"],
  additionalProperties: false,
};

const ajv = new Ajv({ code: { source: true } }); // standalone source
const moduleCode = standaloneCode(ajv, ajv.compile(schema));
writeFileSync(new URL("../generated/validator.cjs", import.meta.url), moduleCode);

Then import the generated validator like any other module:

import validate from "./generated/validator.cjs";
if (!validate(input)) throw new Error("invalid config");

perry compile runs the codegen step, ajv emits generated/validator.cjs (no new Function), and Perry compiles it natively. See test-files/test_ajv_standalone.ts for a runnable, byte-parity-tested sample.

Same convention, other tools

The convention is library-agnostic — point a codegen command at any build-time generator and import its output:

Libraries that JIT at runtime with no standalone mode (e.g. fast-json-stringify, find-my-way) are handled separately — see the eval / new Function strategy.

splash

Configure a native splash screen for iOS and Android. The splash screen appears instantly during cold start, before your app code runs.

Minimal (both platforms share the same splash):

{
  "perry": {
    "splash": {
      "image": "logo/icon-256.png",
      "background": "#FFF5EE"
    }
  }
}

Per-platform overrides:

{
  "perry": {
    "splash": {
      "image": "logo/icon-256.png",
      "background": "#FFF5EE",
      "ios": {
        "image": "logo/splash-ios.png",
        "background": "#FFFFFF"
      },
      "android": {
        "image": "logo/splash-android.png",
        "background": "#FFFFFF"
      }
    }
  }
}

Full custom override (complete control):

{
  "perry": {
    "splash": {
      "ios": {
        "storyboard": "splash/LaunchScreen.storyboard"
      },
      "android": {
        "layout": "splash/splash_background.xml",
        "theme": "splash/themes.xml"
      }
    }
  }
}

Resolution order per platform:

1. Custom file override (storyboard / layout+theme)
2. Platform-specific image/color (splash.{platform}.image)
3. Universal image/color (splash.image)
4. No splash key → blank white screen (backward compatible)

Using npm Packages

Perry natively supports many popular npm packages without any configuration:

// demonstrates: importing built-in stdlib npm packages (project-config.md)
// docs: docs/src/getting-started/project-config.md
// platforms: macos, linux, windows
// run: false

// These four imports are Perry's most-used built-in stdlib shims:
// fastify (HTTP server), mysql2 (db), ioredis (Redis), bcrypt (password
// hashing). They're compiled to native code via Perry's per-package
// implementations — no `compilePackages` needed.
//
// `// run: false` because each one needs a live external service (DB,
// Redis, network port) to actually do anything; the binary still has to
// link cleanly, which is the drift check we want.

import fastify from "fastify"
import mysql from "mysql2/promise"
import Redis from "ioredis"
import bcrypt from "bcrypt"

const app = fastify({ logger: false })
const db = mysql.createPool({ host: "localhost", user: "root", database: "test" })
const redis = new Redis()
const hashed = await bcrypt.hash("hunter2", 10)

console.log(typeof app, typeof db, typeof redis, hashed.length)

These are compiled to native code using Perry’s built-in implementations. See Standard Library for the full list.

For packages not natively supported, use compilePackages for pure TS/JS packages, or the JavaScript runtime fallback for complex packages.

Project Structure

Perry is flexible about project structure. Common patterns:

my-project/
├── package.json
├── src/
│   └── index.ts
└── node_modules/      # Only needed for compilePackages

For UI apps:

my-app/
├── package.json
├── src/
│   ├── index.ts       # Main app entry
│   └── components/    # UI components
└── assets/            # Images, etc.

Compilation

# Compile a file
perry src/index.ts -o build/app

# Compile with a specific target
perry src/index.ts -o build/app --target ios-simulator

# Debug: print intermediate representation
perry src/index.ts --print-hir

See CLI Commands for all options.

Next Steps

• CLI Commands — All compiler commands and flags
• Supported Features — What TypeScript features work
• Standard Library — Supported npm packages