Configuration
Configure PledgeJS with pledge.config.ts.
TL;DR
PledgeJS is configured via pledge.config.ts using defineConfig(). Key options include framework (react/vue/solid/svelte), rsc, ppr, bundler, securityHeaders, i18n, and CDN settings.
Last updated: August 22, 2026
defineConfig
Use defineConfig from pledgestack for type-safe configuration with IDE autocompletion. The native binary reads this file directly.
import { defineConfig } from 'pledgestack';
export default defineConfig({
appDir: 'app',
publicDir: 'public',
outDir: '.pledge',
defaultRuntime: 'node',
framework: 'react', // 'react' | 'vue' | 'solid' | 'svelte'
rsc: true, // React Server Components (React only)
ppr: false, // Partial Prerendering
tailwind: true,
output: 'standalone', // 'standalone' | 'export'
bundler: 'pledgepack', // 'pledgepack' | 'vite' | 'rollup' | 'turbopack' | 'rsbuild' | 'webpack'
securityHeaders: true, // Auto-apply security headers
siteUrl: 'https://example.com', // for sitemap, robots.txt, canonical URLs
});Security Configuration
Configure CSP directives and CORS for API routes. Security headers (X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy, Permissions-Policy, HSTS) are auto-applied by default.
export default defineConfig({
securityHeaders: true,
csp: {
'default-src': "'self'",
'script-src': "'self' 'unsafe-inline'",
'style-src': "'self' 'unsafe-inline'",
'img-src': "'self' data: https:",
},
cors: {
origins: ['https://example.com'],
methods: ['GET', 'POST', 'PUT', 'DELETE'],
},
});i18n
Configure internationalization with locales, a default locale, and a locale prefix strategy.
export default defineConfig({
i18n: {
locales: ['en', 'fr', 'es'],
defaultLocale: 'en',
localePrefix: 'always', // 'always' | 'as-needed'
},
});CDN Purge & Geo-Restriction
Configure CDN cache purging on post-build, and country-based access restriction at the edge (Cloudflare, Vercel, and Deno adapters). paths is required for the CDN purge — without it, the purge step is skipped with a warning instead of running.
export default defineConfig({
cdn: {
provider: 'cloudflare',
zoneId: process.env.CDN_ZONE_ID,
token: process.env.CDN_API_TOKEN,
paths: ['/', '/blog'],
},
geoRestriction: {
mode: 'block', // 'block' | 'allow'
countries: ['KP'], // ISO country codes
},
});Cargo Configuration
Control Rust compilation settings for native addons.
export default defineConfig({
cargo: {
dev: { optLevel: 1, incremental: true },
release: { optLevel: 3, lto: true, strip: true },
},
});Config Resolution Order
PledgeJS resolves configuration in the following order:
pledge.config.tspledge.config.jspledge.config.mjspledge.jsondefaults
Environment Variables
Pledge loads .env files with the following precedence (highest first): .env.[mode].local, .env.[mode], .env.local, .env. Variables are injected via import.meta.env.*.
const apiUrl = import.meta.env.PLEDGE_API_URL;
const isDev = import.meta.env.PLEDGE_DEV;