{ "site": "PledgeJS", "url": "https://pledgejs.org", "description": "PledgeJS is a multi-framework web platform with file-based routing, SSR/SSG/ISR, server components, edge runtime, and a Rust+Zig bundler for native-grade performance.", "nav": [ { "title": "Getting Started", "items": [ { "slug": "installation", "title": "Installation", "url": "https://pledgejs.org/docs/installation" }, { "slug": "project-structure", "title": "Project Structure", "url": "https://pledgejs.org/docs/project-structure" }, { "slug": "cli", "title": "CLI Commands", "url": "https://pledgejs.org/docs/cli" } ] }, { "title": "Building Your Application", "items": [ { "slug": "routing", "title": "Routing", "url": "https://pledgejs.org/docs/routing" }, { "slug": "rendering", "title": "Rendering", "url": "https://pledgejs.org/docs/rendering" }, { "slug": "data-fetching", "title": "Data Fetching & Caching", "url": "https://pledgejs.org/docs/data-fetching" }, { "slug": "frameworks", "title": "Framework Adapters", "url": "https://pledgejs.org/docs/frameworks" }, { "slug": "configuration", "title": "Configuration", "url": "https://pledgejs.org/docs/configuration" }, { "slug": "deploying", "title": "Deploying", "url": "https://pledgejs.org/docs/deploying" } ] }, { "title": "PledgePack", "items": [ { "slug": "pledgepack", "title": "PledgePack Bundler", "url": "https://pledgejs.org/docs/pledgepack" }, { "slug": "pledgepack-cli", "title": "PledgePack CLI", "url": "https://pledgejs.org/docs/pledgepack-cli" } ] } ], "docs": [ { "slug": "installation", "title": "Installation", "description": "Create a new PledgeJS application with create-pledge-app.", "tldr": "Install PledgeJS by running npx create-pledge-app@latest my-app. It scaffolds a new project with your choice of React, Vue, Solid, or Svelte, configures PledgePack as the bundler, and starts the dev server with HMR.", "url": "https://pledgejs.org/docs/installation", "sections": [ { "heading": "System Requirements", "paragraphs": [ "PledgeJS requires Node.js 20.0.0 or later, and supports macOS, Windows, and Linux. For native Rust addons (optional — JS fallbacks exist), a Rust toolchain is needed." ], "code": null, "list": [ "Node.js >= 20.0.0", "pnpm >= 11.x (monorepo workspace)", "Rust toolchain (optional — for PSX native addons; JS fallbacks exist)" ], "table": null }, { "heading": "Automatic Installation", "paragraphs": [ "The fastest way to start a new PledgeJS project is create-pledge-app. It walks you through framework selection (React, Vue, Solid, Svelte), TypeScript, Tailwind CSS, and the App Router." ], "code": { "content": "npx create-pledge-app@latest my-app" }, "list": null, "table": null }, { "heading": "Manual Installation", "paragraphs": [ "To set up a project by hand, install PledgeJS and its peer dependencies. PledgePack is the default bundler and is included automatically." ], "code": { "content": "npm install pledgestack\n# or\npnpm add pledgestack" }, "list": null, "table": null }, { "heading": "Starting the Dev Server", "paragraphs": [ "The CLI command is pledge (not pledgestack). After installing, you can start the dev server, build for production, or start the production server." ], "code": { "content": "npx pledge dev # Start dev server with HMR\nnpx pledge build # Build for production (PledgePack bundler)\nnpx pledge serve # Serve production build" }, "list": null, "table": null } ] }, { "slug": "project-structure", "title": "Project Structure", "description": "A top-level overview of a typical PledgeJS project.", "tldr": "A PledgeJS project uses an app/ directory for file-based routing, pledge.config.ts for configuration, and supports framework-specific extensions like page.tsx (React), page.vue (Vue), and page.svelte (Svelte).", "url": "https://pledgejs.org/docs/project-structure", "sections": [ { "heading": "The app directory", "paragraphs": [ "Routes are defined by folders, and each route segment maps to a folder in the app directory. Special files give each segment its behavior. PledgeJS supports framework-specific extensions: page.tsx (React), page.vue (Vue), page.svelte (Svelte)." ], "code": null, "list": [ "page.tsx / page.vue / page.svelte — makes a route segment publicly accessible", "layout.* — shared UI wrapping a segment and its children", "loading.* — a Suspense fallback for a segment", "error.* — an error boundary for a segment", "not-found.* — 404 UI for a segment", "template.* — wrapper that re-renders on navigation", "head.* — head metadata for a segment", "route.ts — a server-only API endpoint", "opengraph-image.* / twitter-image.* — OG/Twitter card images" ], "table": null }, { "heading": "Colocation", "paragraphs": [ "Files can be colocated inside route folders without becoming routable, since only page.* and route.ts are publicly addressable. This keeps components, tests, and styles close to the routes that use them." ], "code": null, "list": null, "table": null }, { "heading": "Configuration File", "paragraphs": [ "PledgeJS uses pledge.config.ts as its configuration file. It is validated at load time — invalid values produce clear error messages before the server starts." ], "code": { "filename": "pledge.config.ts", "content": "import { defineConfig } from 'pledgestack';\n\nexport default defineConfig({\n appDir: 'app',\n framework: 'react', // 'react' | 'vue' | 'solid' | 'svelte'\n bundler: 'pledgepack',\n rsc: true, // React Server Components (React only)\n ppr: false, // Partial Prerendering\n tailwind: true,\n});" }, "list": null, "table": null } ] }, { "slug": "cli", "title": "CLI Commands", "description": "The pledge CLI provides dev, build, and project management commands.", "tldr": "The pledge CLI is the primary interface for PledgeJS. Use pledge dev for the dev server, pledge build for production builds, pledge serve to serve the build, and pledge doctor for health checks.", "url": "https://pledgejs.org/docs/cli", "sections": [ { "heading": "Core Commands", "paragraphs": [ "The CLI command is pledge. After installing pledgestack, use npx pledge or add it to your scripts." ], "code": null, "list": null, "table": { "headers": [ "Command", "Description" ], "rows": [ [ "pledge dev", "Start dev server with HMR" ], [ "pledge build", "Build for production (PledgePack bundler)" ], [ "pledge serve", "Serve production build" ], [ "pledge create ", "Scaffold a new project from template" ], [ "pledge init", "Initialize PledgeJS in existing project" ], [ "pledge info", "Show project diagnostics" ], [ "pledge doctor", "Health checks (Rust toolchain, Cargo, env)" ] ] } }, { "heading": "Code Quality", "paragraphs": [ "Built-in commands for linting, type checking, testing, and formatting." ], "code": null, "list": null, "table": { "headers": [ "Command", "Description" ], "rows": [ [ "pledge lint", "Run ESLint with PledgeJS rules" ], [ "pledge typecheck", "TypeScript type checking" ], [ "pledge test", "Run Vitest + Rust test runner" ], [ "pledge fmt", "Format Rust code (cargo fmt)" ], [ "pledge clean", "Remove build artifacts and caches" ] ] } }, { "heading": "Rust Crate Management", "paragraphs": [ "PledgeJS integrates Rust native addons (PSX). Manage them with these commands." ], "code": null, "list": null, "table": { "headers": [ "Command", "Description" ], "rows": [ [ "pledge add ", "Add a Rust crate (PSX integration)" ], [ "pledge remove ", "Remove a Rust crate" ], [ "pledge list", "List installed Rust crates" ], [ "pledge update ", "Update a Rust crate" ], [ "pledge bench", "Benchmark Rust addons vs JS fallbacks" ] ] } }, { "heading": "Analysis & Tooling", "paragraphs": [ "Commands for bundle analysis, documentation, Docker setup, and more." ], "code": null, "list": null, "table": { "headers": [ "Command", "Description" ], "rows": [ [ "pledge analyze", "Bundle analysis — per-module .node size breakdown" ], [ "pledge why ", "Trace why a module is in the bundle" ], [ "pledge docs", "Generate API reference (TypeDoc)" ], [ "pledge docker [--optimized]", "Generate Dockerfile, .dockerignore, docker-compose.yml (--optimized: Rust-addon multi-stage build)" ], [ "pledge storybook", "Set up Storybook" ], [ "pledge codemod", "Run code transformations" ], [ "pledge upgrade", "Upgrade PledgeJS with codemods" ], [ "pledge search [query]", "Index pages and search content (full-text search)" ], [ "pledge generate-route-types", "Generate typed route declarations" ], [ "pledge check-routes", "Detect route conflicts" ], [ "pledge sync-aliases", "Sync tsconfig path aliases" ] ] } } ] }, { "slug": "routing", "title": "Routing Fundamentals", "description": "Learn the fundamentals of file-based routing in PledgeJS.", "tldr": "PledgeJS uses file-based routing: every folder inside app/ maps to a URL segment. Special files like page.tsx, layout.*, route.ts, and middleware.ts define the behavior of each segment.", "url": "https://pledgejs.org/docs/routing", "sections": [ { "heading": "Defining Routes", "paragraphs": [ "Every folder inside app represents a route segment that maps to a URL segment. Nested folders create nested routes automatically, no configuration file required." ], "code": { "filename": "app/dashboard/settings/page.tsx", "content": "export default function Settings() {\n return

Settings

;\n}" }, "list": null, "table": null }, { "heading": "Dynamic Segments", "paragraphs": [ "Wrap a folder name in square brackets to create a dynamic segment that's populated at request time, such as a blog slug or product id." ], "code": { "filename": "app/blog/[slug]/page.tsx", "content": "export default async function Page({\n params,\n}: {\n params: Promise<{ slug: string }>;\n}) {\n const { slug } = await params;\n return

Post: {slug}

;\n}" }, "list": null, "table": null }, { "heading": "Route Patterns", "paragraphs": [ "PledgeJS supports the full range of route patterns from the App Router convention." ], "code": null, "list": [ "[param] — dynamic segment", "[...param] — catch-all segment", "[[...param]] — optional catch-all segment", "(group) — route group (does not affect URL path)", "@slot — parallel route slot", "(..)folder — intercepting route" ], "table": null }, { "heading": "Route Groups", "paragraphs": [ "Wrapping a folder name in parentheses, like (marketing), opts it out of the URL path while still letting you organize routes and share layouts." ], "code": null, "list": null, "table": null }, { "heading": "API Routes", "paragraphs": [ "Use route.ts to define server-only API endpoints with HTTP method handlers. CORS middleware and XSS sanitization are auto-applied." ], "code": { "filename": "app/api/posts/route.ts", "content": "export async function GET() {\n const posts = await getPosts();\n return Response.json(posts);\n}\n\nexport async function POST(request: Request) {\n const body = await request.json();\n const post = await createPost(body);\n return Response.json(post, { status: 201 });\n}" }, "list": null, "table": null }, { "heading": "Middleware", "paragraphs": [ "middleware.ts runs before every request. Use it for redirects (open-redirect validated), rewrites, headers, and short-circuiting. Matcher config supports glob patterns, param patterns, and regex." ], "code": null, "list": null, "table": null } ] }, { "slug": "rendering", "title": "Rendering", "description": "SSR, SSG, ISR, RSC, and Partial Prerendering in PledgeJS.", "tldr": "PledgeJS supports server-side rendering (SSR), static site generation (SSG), incremental static regeneration (ISR), React Server Components (RSC, React-only), and Partial Prerendering (PPR) — a static shell with streaming dynamic holes.", "url": "https://pledgejs.org/docs/rendering", "sections": [ { "heading": "Server-Side Rendering", "paragraphs": [ "renderSSR() renders pages with layout chains, error boundaries, and Suspense loading states (React). Each renderer adapter implements its own SSR via the framework's native APIs. Streaming SSR is supported — React uses renderToPipeableStream with Suspense boundaries for true progressive streaming." ], "code": null, "list": null, "table": null }, { "heading": "Static Site Generation", "paragraphs": [ "Routes are prerendered at build time whenever possible. Use generateStaticParams to specify which dynamic routes to pre-render. Use static-export mode for a fully static output." ], "code": null, "list": null, "table": null }, { "heading": "React Server Components", "paragraphs": [ "RSC is React-only. PledgeJS integrates react-server-dom-webpack for flight payload generation, RSC streaming, and client manifests. Flight payloads are streamed progressively — chunks are pushed to the client as they arrive rather than buffered into a single blob before anything is sent. Other frameworks (Vue, Solid, Svelte) use standard SSR with hydration." ], "code": null, "list": null, "table": null }, { "heading": "Partial Prerendering (PPR)", "paragraphs": [ "PPR prerenders a static shell at build time and streams dynamic holes at request time. Rust-based PPR via rust-ppr.ts with JS fallback. Set ppr: true in your config to enable." ], "code": { "filename": "pledge.config.ts", "content": "export default defineConfig({\n ppr: true, // static shell + streaming dynamic holes\n});" }, "list": null, "table": null }, { "heading": "Client Components", "paragraphs": [ "Add the 'use client' directive at the top of a file to opt a component and its imports into the client bundle, which is required for interactivity like state and event handlers." ], "code": { "filename": "app/ui/counter.tsx", "content": "'use client';\n\nimport { useState } from 'react';\n\nexport default function Counter() {\n const [count, setCount] = useState(0);\n return ;\n}" }, "list": null, "table": null }, { "heading": "JIT Templates", "paragraphs": [ "A hot route template compiler profiles SSR renders and compiles frequently-rendered routes to native functions that bypass React reconciliation. Uses the rust-jit-templates NAPI addon with JS fallback." ], "code": null, "list": null, "table": null } ] }, { "slug": "data-fetching", "title": "Data Fetching & Caching", "description": "Fetch, cache, and revalidate data in PledgeJS.", "tldr": "In PledgeJS, Server Components can be async and await data directly. cachedFetch() supports force-cache, no-store, and ISR modes with tag-based revalidation. SSRF protection is built in.", "url": "https://pledgejs.org/docs/data-fetching", "sections": [ { "heading": "Fetching on the Server", "paragraphs": [ "Server Components can be declared async, letting you await data directly in the component body without a separate hook or client-side request." ], "code": { "filename": "app/posts/page.tsx", "content": "export default async function Posts() {\n const res = await fetch('https://api.example.com/posts');\n const posts = await res.json();\n\n return (\n
    \n {posts.map((p: { id: string; title: string }) => (\n
  • {p.title}
    • \n ))}\n
\n );\n}" }, "list": null, "table": null }, { "heading": "Fetch Cache", "paragraphs": [ "cachedFetch() supports force-cache, no-store, and isr modes with tag-based revalidation. LRU eviction when cache exceeds max entries (10,000 default). Periodic cleanup of expired entries is built in." ], "code": null, "list": null, "table": null }, { "heading": "Cache Invalidation", "paragraphs": [ "Use revalidateTag() and revalidatePath() to invalidate cached data. PledgeJS supports persistent cache, remote cache, and a cache-invalidation worker." ], "code": { "content": "import { revalidateTag, revalidatePath } from 'pledgestack';\n\n// Invalidate all fetches tagged 'posts'\nrevalidateTag('posts');\n\n// Invalidate a specific path\nrevalidatePath('/blog');" }, "list": null, "table": null }, { "heading": "Query Memoization", "paragraphs": [ "Identical data fetches within the same request are automatically deduplicated, so you don't need to worry about multiple components fetching the same data." ], "code": null, "list": null, "table": null }, { "heading": "SSRF Protection", "paragraphs": [ "Server-side fetch validates URLs against private/internal address ranges before fetching, preventing server-side request forgery attacks." ], "code": null, "list": null, "table": null }, { "heading": "Server Actions", "paragraphs": [ "Use serverAction() and getServerAction() to call server-side code directly from forms or event handlers. CSRF token validation is enforced on all POST/PUT/DELETE/PATCH requests; Server Actions are exempt. The useActionState hook is available for React." ], "code": null, "list": null, "table": null }, { "heading": "Server Utilities", "paragraphs": [ "PledgeJS provides the standard set of server utilities for reading request data and controlling flow." ], "code": null, "list": [ "cookies() — read and set cookies", "headers() — read request headers", "searchParams() — read URL search params", "params() — read route params", "redirect() — redirect to another route", "notFound() — render the 404 page", "after() — schedule work after the response is sent", "connection() — access the underlying connection", "draftMode() — toggle draft mode" ], "table": null } ] }, { "slug": "frameworks", "title": "Framework Adapters", "description": "Build with React, Vue, Solid, or Svelte using renderer adapters.", "tldr": "PledgeJS is framework-agnostic. Set framework in pledge.config.ts and install the corresponding pledgestack-renderer-* package. React has full RSC support; Vue, Solid, and Svelte use SSR with hydration.", "url": "https://pledgejs.org/docs/frameworks", "sections": [ { "heading": "Framework-Agnostic Core", "paragraphs": [ "PledgeJS is framework-agnostic. The core runtime (routing, SSR, API routes, middleware, caching) works with any UI framework via renderer adapters. Set framework in pledge.config.ts and install the corresponding pledgestack-renderer-* package." ], "code": null, "list": null, "table": { "headers": [ "Framework", "Package", "RSC", "SSR", "Streaming", "PPR", "Status" ], "rows": [ [ "React", "pledgestack-renderer-react", "Yes", "Yes", "Yes", "Yes", "Full support" ], [ "Vue", "pledgestack-renderer-vue", "No", "Yes", "Partial", "Yes", "SSR + hydration" ], [ "Solid", "pledgestack-renderer-solid", "No", "Yes", "Partial", "Yes", "SSR + hydration" ], [ "Svelte", "pledgestack-renderer-svelte", "No", "Yes", "Partial", "Yes", "SSR + hydration" ] ] } }, { "heading": "RSC is React-Only", "paragraphs": [ "React Server Components are React-only. Other frameworks use standard SSR with hydration. Streaming for Vue/Solid/Svelte uses async SSR (no Suspense-style progressive streaming). React uses renderToPipeableStream with Suspense boundaries for true progressive streaming." ], "code": null, "list": null, "table": null }, { "heading": "PledgePack Framework Support", "paragraphs": [ "PledgePack, the Rust+Zig bundler, supports additional frameworks through adapters." ], "code": null, "list": null, "table": { "headers": [ "Framework", "Status", "File Types" ], "rows": [ [ "React", "Full", ".tsx, .jsx, Fast Refresh, automatic JSX runtime" ], [ "Solid", "Full", ".tsx, .jsx, automatic JSX with solid-js" ], [ "Vue", "Transform", ".vue (SFC), scoped CSS, script setup" ], [ "Svelte", "Transform", ".svelte (SFC), scoped CSS, render functions" ], [ "Astro", "Transform", ".astro, frontmatter, islands-ready" ], [ "Next.js", "Adapter", "App Router, Pages Router, API routes, SSR" ], [ "TanStack", "Adapter", "File-based routing, route tree generation" ], [ "PledgeJS", "Adapter", "React frontend + Rust backend, .rs/.psx" ], [ "Vanilla TS/JS", "Full", ".ts, .js, .mjs" ] ] } } ] }, { "slug": "configuration", "title": "Configuration", "description": "Configure PledgeJS with pledge.config.ts.", "tldr": "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.", "url": "https://pledgejs.org/docs/configuration", "sections": [ { "heading": "defineConfig", "paragraphs": [ "Use defineConfig from pledgestack for type-safe configuration with IDE autocompletion. The native binary reads this file directly." ], "code": { "filename": "pledge.config.ts", "content": "import { defineConfig } from 'pledgestack';\n\nexport default defineConfig({\n appDir: 'app',\n publicDir: 'public',\n outDir: '.pledge',\n defaultRuntime: 'node',\n framework: 'react', // 'react' | 'vue' | 'solid' | 'svelte'\n rsc: true, // React Server Components (React only)\n ppr: false, // Partial Prerendering\n tailwind: true,\n output: 'standalone', // 'standalone' | 'export'\n bundler: 'pledgepack', // 'pledgepack' | 'vite' | 'rollup' | 'turbopack' | 'rsbuild' | 'webpack'\n securityHeaders: true, // Auto-apply security headers\n siteUrl: 'https://example.com', // for sitemap, robots.txt, canonical URLs\n});" }, "list": null, "table": null }, { "heading": "Security Configuration", "paragraphs": [ "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." ], "code": { "content": "export default defineConfig({\n securityHeaders: true,\n csp: {\n 'default-src': \"'self'\",\n 'script-src': \"'self' 'unsafe-inline'\",\n 'style-src': \"'self' 'unsafe-inline'\",\n 'img-src': \"'self' data: https:\",\n },\n cors: {\n origins: ['https://example.com'],\n methods: ['GET', 'POST', 'PUT', 'DELETE'],\n },\n});" }, "list": null, "table": null }, { "heading": "i18n", "paragraphs": [ "Configure internationalization with locales, a default locale, and a locale prefix strategy." ], "code": { "content": "export default defineConfig({\n i18n: {\n locales: ['en', 'fr', 'es'],\n defaultLocale: 'en',\n localePrefix: 'always', // 'always' | 'as-needed'\n },\n});" }, "list": null, "table": null }, { "heading": "CDN Purge & Geo-Restriction", "paragraphs": [ "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." ], "code": { "content": "export default defineConfig({\n cdn: {\n provider: 'cloudflare',\n zoneId: process.env.CDN_ZONE_ID,\n token: process.env.CDN_API_TOKEN,\n paths: ['/', '/blog'],\n },\n geoRestriction: {\n mode: 'block', // 'block' | 'allow'\n countries: ['KP'], // ISO country codes\n },\n});" }, "list": null, "table": null }, { "heading": "Cargo Configuration", "paragraphs": [ "Control Rust compilation settings for native addons." ], "code": { "content": "export default defineConfig({\n cargo: {\n dev: { optLevel: 1, incremental: true },\n release: { optLevel: 3, lto: true, strip: true },\n },\n});" }, "list": null, "table": null }, { "heading": "Config Resolution Order", "paragraphs": [ "PledgeJS resolves configuration in the following order:" ], "code": null, "list": [ "pledge.config.ts", "pledge.config.js", "pledge.config.mjs", "pledge.json", "defaults" ], "table": null }, { "heading": "Environment Variables", "paragraphs": [ "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.*." ], "code": { "content": "const apiUrl = import.meta.env.PLEDGE_API_URL;\nconst isDev = import.meta.env.PLEDGE_DEV;" }, "list": null, "table": null } ] }, { "slug": "deploying", "title": "Deploying", "description": "Take your PledgeJS application to production.", "tldr": "Deploy PledgeJS apps anywhere: Node.js servers, Docker containers, static exports, or edge runtimes. Run pledge build then pledge serve, or use pledge docker --optimized for a Rust-addon-aware multi-stage build.", "url": "https://pledgejs.org/docs/deploying", "sections": [ { "heading": "Production Build", "paragraphs": [ "Running the build command compiles and optimizes your app for production using the PledgePack bundler, generating static assets and server bundles where applicable." ], "code": { "content": "pledge build\npledge serve" }, "list": null, "table": null }, { "heading": "Docker", "paragraphs": [ "Use pledge docker to generate a Dockerfile, .dockerignore, and docker-compose.yml tailored to your PledgeJS project. Add --optimized for a Rust-addon-aware multi-stage build that compiles the native addons in a dedicated stage and ships only the resulting .node/.so files, rather than a Rust toolchain, in the runtime image." ], "code": { "content": "pledge docker\npledge docker --optimized" }, "list": null, "table": null }, { "heading": "Hosting Options", "paragraphs": [ "A PledgeJS app can be deployed to any Node.js server, a Docker container, or a static export, depending on which features your routes rely on. The standalone output mode produces a self-contained server bundle." ], "code": null, "list": [ "standalone — self-contained server bundle for any Node.js host", "export — fully static output for CDN/static hosting", "Docker — containerized deployment with generated Dockerfile" ], "table": null }, { "heading": "Edge Runtime", "paragraphs": [ "PledgeJS supports edge runtime deployment. Multi-region edge caching with invalidation is built in. Not every workload is a good fit for the edge — routes with heavy, region-locked dependencies are often better left on a traditional server runtime." ], "code": null, "list": null, "table": null }, { "heading": "Deployment Adapters", "paragraphs": [ "Platform adapters wrap the PledgeJS edge handler for each deployment target. Every adapter runs the same edge security pipeline — rate limiting, bot detection, geo restriction, and config-driven CSP — so a request is treated identically regardless of platform. Secrets resolve through the platform's native store: Cloudflare env bindings, Vercel Edge Config, or Deno KV." ], "code": { "content": "// Vercel Edge — export as the edge entry\nimport { createVercelEdgeHandler } from 'pledgestack/adapters/vercel';\nexport default createVercelEdgeHandler({ config });\n\n// Deno Deploy\nimport { createDenoHandler } from 'pledgestack/adapters/deno';\nDeno.serve(createDenoHandler({ config }));" }, "list": null, "table": { "headers": [ "Platform", "Entry Point", "Import Path" ], "rows": [ [ "Cloudflare Workers / Pages", "createCloudflareAdapter", "pledgestack/adapters/cloudflare" ], [ "Vercel Edge", "createVercelEdgeHandler", "pledgestack/adapters/vercel" ], [ "Deno Deploy", "createDenoHandler", "pledgestack/adapters/deno" ], [ "Netlify Functions", "createNetlifyHandler", "pledgestack/adapters/netlify" ], [ "AWS Lambda / API Gateway", "createLambdaHandler", "pledgestack/adapters/lambda" ], [ "Azure Functions / Static Web Apps", "createAzureHandler", "pledgestack/adapters/azure" ], [ "Google Cloud Functions", "createGcloudHandler", "pledgestack/adapters/gcloud" ], [ "Fastly Compute", "createFastlyHandler", "pledgestack/adapters/fastly" ], [ "Supabase Edge Functions", "createSupabaseHandler", "pledgestack/adapters/supabase" ] ] } }, { "heading": "Health Checks", "paragraphs": [ "Before deploying, run pledge doctor to verify your Rust toolchain, Cargo, environment, and production readiness." ], "code": { "content": "pledge doctor" }, "list": null, "table": null } ] }, { "slug": "pledgepack", "title": "PledgePack Bundler", "description": "The Rust + Zig bundler and dev server that powers PledgeJS.", "tldr": "PledgePack is the default bundler and dev server for PledgeJS, written in Rust and Zig. It uses Oxc for transforms, Lightning CSS for styles, and a Zig C ABI for hot-path file I/O. It replaces Vite, webpack, and Rollup with a single native toolchain.", "url": "https://pledgejs.org/docs/pledgepack", "sections": [ { "heading": "Architecture", "paragraphs": [ "PledgePack is a Rust + Zig bundler and dev server. It uses Oxc for transforms, Lightning CSS for styles, Axum for the dev server, and a Zig C ABI for hot-path file I/O and SIMD scanning. The Rust orchestrator handles the engine, resolver, cache, dev server, optimizer, and JS plugin host. The Zig layer handles file I/O, module graph, SIMD scanning, hashing, and memory-mapped I/O." ], "code": null, "list": null, "table": null }, { "heading": "Project Structure", "paragraphs": [ "PledgePack is organized as a Rust workspace with a Zig native library." ], "code": { "content": "pledgepack/\n├── Cargo.toml # Rust workspace\n├── build.zig # Zig build script\n├── package.json # npm package (bin: pledgepack, pledge)\n├── native-sys/ # Rust FFI bindings to Zig\n│ └── zig/ # Zig native library\n│ ├── io.zig # File I/O (mmap, thread pool)\n│ ├── graph.zig # Arena-allocated module graph\n│ └── simd.zig # SIMD source scanning\n├── crates/\n│ ├── cli/ # CLI entry point (binary: pledge)\n│ ├── core/ # Engine, config, transform pipeline\n│ ├── cache/ # Function-level incremental cache\n│ ├── resolver/ # Module resolution\n│ ├── dev-server/ # Dev server + HMR + error overlay\n│ ├── optimizer/ # Tree shaking, code splitting\n│ ├── js-plugin-host/ # Vite-compatible JS plugin API (QuickJS)\n│ ├── wasm-plugin-host/ # WebAssembly plugin host\n│ ├── adapter-react/ # React JSX + Fast Refresh\n│ ├── adapter-solid/ # Solid.js JSX adapter\n│ ├── adapter-next/ # Next.js adapter\n│ ├── adapter-tanstack/ # TanStack Router adapter\n│ ├── adapter-pledgestack/ # PledgeStack adapter\n│ └── task-system/ # Parallel task execution engine\n└── docs/" }, "list": null, "table": null }, { "heading": "Prerequisites", "paragraphs": [ "Building PledgePack from source requires Rust (stable, edition 2024) and Zig (0.14.0+)." ], "code": { "content": "git clone https://github.com/pledgeandgrow/pledgepack\ncd pledgepack\n\n# Build Zig native library\nzig build -Doptimize=ReleaseFast\n\n# Build Rust\ncargo build --release" }, "list": null, "table": null }, { "heading": "Transform Pipeline", "paragraphs": [ "The transform pipeline lives in crates/core/src/transform/ and is split into focused submodules." ], "code": null, "list": [ "js.rs — JS/TS/JSX via Oxc, React Fast Refresh, dynamic import detection", "css.rs — Lightning CSS, CSS Modules, PostCSS/Tailwind, Sass/SCSS", "assets.rs — JSON, static assets, WASM, shaders", "sfc.rs — Vue, Svelte, Astro Single-File Components", "env.rs — Environment variables, define, import.meta.glob", "data.rs — MDX, GraphQL, YAML, CSV, TSV, TOML", "utils.rs — Source maps, Web Worker import transforms" ], "table": null } ] }, { "slug": "pledgepack-cli", "title": "PledgePack CLI", "description": "The pledgepack CLI for bundling, dev server, and scaffolding.", "tldr": "The pledgepack CLI (alias: pledge) provides dev, build, serve, create, analyze, and migrate commands. It can be used standalone without PledgeJS.", "url": "https://pledgejs.org/docs/pledgepack-cli", "sections": [ { "heading": "Installation", "paragraphs": [ "PledgePack can be installed globally or as a dev dependency. The CLI command is pledge (alias: pledgepack)." ], "code": { "content": "# Global install\nnpm install -g pledgepack\n\n# Or as a dev dependency\nnpm install --save-dev pledgepack" }, "list": null, "table": null }, { "heading": "Development Server", "paragraphs": [ "Start the dev server with HMR, custom ports, auto-open browser, or HTTPS." ], "code": { "content": "pledgepack dev # Start on port 3000\npledgepack dev --port 8080 # Custom port\npledgepack dev --open # Auto-open browser\npledgepack dev --https # HTTPS with self-signed certs" }, "list": null, "table": null }, { "heading": "Production Build", "paragraphs": [ "Build for production with optional watch mode, profiling, type checking, and bundle size budgets." ], "code": { "content": "pledgepack build # Build to dist/\npledgepack build --watch # Watch mode\npledgepack build --profile # Profile build phases\npledgepack build --type-check # TypeScript type checking\npledgepack build --check-budgets # Bundle size budgets" }, "list": null, "table": null }, { "heading": "Project Scaffolding", "paragraphs": [ "Create new projects with framework-specific templates." ], "code": { "content": "pledgepack create react my-app\npledgepack create vue my-app\npledgepack create svelte my-app\npledgepack create solid my-app\npledgepack create next my-app\npledgepack create tanstack my-app\npledgepack create pledgestack my-app\npledgepack create vanilla my-app\npledgepack create my-app # Defaults to pledgestack" }, "list": null, "table": null }, { "heading": "Other Commands", "paragraphs": [ "PledgePack includes commands for testing, benchmarking, analysis, caching, and more." ], "code": null, "list": null, "table": { "headers": [ "Command", "Description" ], "rows": [ [ "pledgepack serve", "Serve static files on port 4000" ], [ "pledgepack preview", "Alias for serve" ], [ "pledgepack test", "Run tests (Vitest-compatible API)" ], [ "pledgepack bench", "Benchmark build performance" ], [ "pledgepack analyze --graph", "Bundle analyzer with dependency graph" ], [ "pledgepack dashboard", "Build telemetry dashboard" ], [ "pledgepack cache clear", "Clear disk cache" ], [ "pledgepack cache stats", "Show cache statistics" ], [ "pledgepack doctor", "Diagnose build issues" ], [ "pledgepack init", "Add PledgePack to existing project" ], [ "pledgepack migrate", "Migrate from Vite/webpack/CRA" ], [ "pledgepack schema", "Generate JSON Schema for config" ], [ "pledgepack playground", "Interactive transform REPL" ], [ "pledgepack completions --shell bash", "Shell completions" ], [ "pledgepack manpages", "Generate man pages" ] ] } } ] } ] }