{"id":50916391,"url":"https://github.com/quinnjr/ngx-bun","last_synced_at":"2026-06-16T15:32:14.744Z","repository":{"id":335218339,"uuid":"1127306055","full_name":"quinnjr/ngx-bun","owner":"quinnjr","description":"🚀 Angular 19+ SSR adapter for Bun - High-performance server-side rendering with Bun's blazing fast runtime","archived":false,"fork":false,"pushed_at":"2026-06-08T20:15:51.000Z","size":739,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T22:13:25.087Z","etag":null,"topics":["angular","angular-19","angular-cli","angular-ssr","angular-universal","bun","hydration","nodejs","prerendering","schematics","server-side-rendering","ssg","ssr","static-site-generation","typescript","web-performance"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quinnjr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"patreon":"PegasusHeavyIndustries"}},"created_at":"2026-01-03T16:02:27.000Z","updated_at":"2026-04-23T20:54:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/quinnjr/ngx-bun","commit_stats":null,"previous_names":["pegasusheavy/ngx-bun","quinnjr/ngx-bun"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/quinnjr/ngx-bun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quinnjr%2Fngx-bun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quinnjr%2Fngx-bun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quinnjr%2Fngx-bun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quinnjr%2Fngx-bun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quinnjr","download_url":"https://codeload.github.com/quinnjr/ngx-bun/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quinnjr%2Fngx-bun/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34412788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","angular-19","angular-cli","angular-ssr","angular-universal","bun","hydration","nodejs","prerendering","schematics","server-side-rendering","ssg","ssr","static-site-generation","typescript","web-performance"],"created_at":"2026-06-16T15:32:14.584Z","updated_at":"2026-06-16T15:32:14.737Z","avatar_url":"https://github.com/quinnjr.png","language":"TypeScript","funding_links":["https://patreon.com/PegasusHeavyIndustries"],"categories":[],"sub_categories":[],"readme":"# @pegasusheavy/ngx-bun\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://angular.io/assets/images/logos/angular/angular.svg\" width=\"80\" alt=\"Angular\" /\u003e\n  \u003cspan style=\"font-size: 48px; margin: 0 20px;\"\u003e+\u003c/span\u003e\n  \u003cimg src=\"https://bun.sh/logo.svg\" width=\"80\" alt=\"Bun\" /\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cstrong\u003eHigh-performance SSR/SSG adapter for Angular 19+ using Bun's built-in server\u003c/strong\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e •\n  \u003ca href=\"#api\"\u003eAPI\u003c/a\u003e •\n  \u003ca href=\"#prerendering\"\u003ePrerendering\u003c/a\u003e\n\u003c/div\u003e\n\n---\n\n## Features\n\n- 🚀 **Blazing Fast** - Leverages Bun's high-performance HTTP server and runtime\n- 📦 **Full SSR Support** - Complete server-side rendering for Angular 19+\n- 🏗️ **SSG/Prerendering** - Generate static HTML files at build time\n- 🔄 **Automatic Hydration** - Seamless client-side hydration\n- 📁 **Static File Serving** - Optimized static asset serving with compression\n- 💾 **Built-in Caching** - LRU cache for rendered pages\n- 🛠️ **Angular CLI Integration** - Schematics for easy setup with `ng add`\n- 🔧 **Custom Builders** - Angular CLI builders for development and production\n\n## Requirements\n\n- **Angular** 19.0.0 or higher\n- **Bun** 1.0.0 or higher\n- **Node.js** 20.0.0 or higher (for Angular CLI)\n\n## Installation\n\n### Using Angular CLI (Recommended)\n\n```bash\nng add @pegasusheavy/ngx-bun\n```\n\nThis will:\n1. Install the package and dependencies\n2. Generate the server file (`server.ts`)\n3. Create server-side configuration files\n4. Update `angular.json` with SSR targets\n5. Add npm scripts for development and production\n\n### Manual Installation\n\n```bash\n# Install the package\npnpm add @pegasusheavy/ngx-bun\n\n# Install peer dependencies\npnpm add @angular/ssr @angular/platform-server\n```\n\n## Quick Start\n\n### 1. Add SSR to your Angular project\n\n```bash\nng add @pegasusheavy/ngx-bun\n```\n\n### 2. Start the development server\n\n```bash\npnpm dev:ssr\n```\n\n### 3. Build for production\n\n```bash\npnpm build:ssr\n```\n\n### 4. Serve production build\n\n```bash\npnpm serve:ssr\n```\n\n## Configuration\n\n### Server Configuration\n\nThe generated `server.ts` file can be customized:\n\n```typescript\nimport { createBunServer, createBunAngularEngine } from '@pegasusheavy/ngx-bun';\n\nconst engine = createBunAngularEngine({\n  bootstrap: () =\u003e import('./src/main.server'),\n  browserDistFolder: './dist/my-app/browser',\n\n  // Cache configuration\n  enableCache: true,\n  maxCacheSize: 100,\n  cacheTtl: 300_000, // 5 minutes\n});\n\ncreateBunServer({\n  engine,\n  port: 4000,\n  hostname: 'localhost',\n\n  // Enable request logging\n  logging: true,\n\n  // Routes to skip SSR (client-only)\n  clientOnlyRoutes: ['/admin/*'],\n\n  // Development mode\n  development: process.env.NODE_ENV !== 'production',\n});\n```\n\n### Route Rendering Configuration\n\nConfigure how each route is rendered in `app.routes.server.ts`:\n\n```typescript\nimport { RenderMode, ServerRoute } from '@angular/ssr';\n\nexport const serverRoutes: ServerRoute[] = [\n  // Client-side only (no SSR)\n  { path: 'admin/**', renderMode: RenderMode.Client },\n\n  // Prerendered at build time (SSG)\n  { path: 'about', renderMode: RenderMode.Prerender },\n  { path: 'blog/:slug', renderMode: RenderMode.Prerender },\n\n  // Server-side rendered on each request (SSR)\n  { path: '**', renderMode: RenderMode.Server },\n];\n```\n\n### Angular.json Targets\n\nThe schematic adds these targets to your `angular.json`:\n\n```json\n{\n  \"serve-ssr\": {\n    \"builder\": \"@pegasusheavy/ngx-bun:serve\",\n    \"options\": {\n      \"browserTarget\": \"my-app:build\",\n      \"port\": 4000\n    }\n  },\n  \"prerender\": {\n    \"builder\": \"@pegasusheavy/ngx-bun:prerender\",\n    \"options\": {\n      \"browserTarget\": \"my-app:build:production\",\n      \"routes\": [\"/\", \"/about\", \"/contact\"]\n    }\n  }\n}\n```\n\n## API\n\n### `createBunAngularEngine(options)`\n\nCreates the Angular SSR engine.\n\n```typescript\ninterface BunAngularEngineOptions {\n  // Angular bootstrap function\n  bootstrap: () =\u003e Promise\u003cApplicationRef\u003e;\n\n  // Path to browser distribution\n  browserDistFolder: string;\n\n  // Path to server distribution (optional)\n  serverDistFolder?: string;\n\n  // Custom index.html path (optional)\n  indexHtml?: string;\n\n  // Additional providers (optional)\n  providers?: Provider[];\n\n  // Enable render caching (default: true)\n  enableCache?: boolean;\n\n  // Max cache entries (default: 100)\n  maxCacheSize?: number;\n\n  // Cache TTL in ms (default: 300000)\n  cacheTtl?: number;\n}\n```\n\n### `createBunServer(options)`\n\nCreates and starts the Bun server.\n\n```typescript\ninterface BunServerOptions {\n  // The Angular engine instance\n  engine: BunAngularEngine;\n\n  // Server port (default: 4000)\n  port?: number;\n\n  // Server hostname (default: 'localhost')\n  hostname?: string;\n\n  // Enable static file serving (default: true)\n  serveStatic?: boolean;\n\n  // Static files directory\n  staticDir?: string;\n\n  // Development mode (default: false)\n  development?: boolean;\n\n  // Enable request logging (default: false)\n  logging?: boolean;\n\n  // Routes to skip SSR\n  clientOnlyRoutes?: string[];\n\n  // TLS configuration for HTTPS\n  tls?: { cert: string; key: string };\n\n  // Server start callback\n  onStart?: (server: Server) =\u003e void;\n}\n```\n\n### `createRequestHandler(options)`\n\nCreates a request handler for custom server setups.\n\n```typescript\nimport { createRequestHandler } from '@pegasusheavy/ngx-bun';\n\nconst handler = createRequestHandler({\n  engine,\n  staticHandler,\n  logging: true,\n});\n\n// Use with Bun.serve directly\nBun.serve({\n  fetch: handler,\n  port: 4000,\n});\n```\n\n### `createStaticFileHandler(options)`\n\nCreates a static file handler with caching and compression.\n\n```typescript\ninterface StaticFileOptions {\n  // Root directory for static files\n  root: string;\n\n  // Index file name (default: 'index.html')\n  index?: string;\n\n  // Enable compression (default: true)\n  compression?: boolean;\n\n  // Custom MIME types\n  mimeTypes?: Record\u003cstring, string\u003e;\n\n  // Cache control header\n  cacheControl?: string | ((path: string) =\u003e string);\n}\n```\n\n## Prerendering (SSG)\n\n### Using Angular CLI\n\n```bash\nng run my-app:prerender\n```\n\n### Programmatic API\n\n```typescript\nimport { prerenderRoutes } from '@pegasusheavy/ngx-bun/prerender';\n\nconst result = await prerenderRoutes({\n  engineOptions: {\n    bootstrap,\n    browserDistFolder: './dist/browser',\n  },\n  routes: ['/', '/about', '/blog/post-1', '/blog/post-2'],\n  outputDir: './dist/prerendered',\n  concurrency: 5,\n  generateSitemap: true,\n  baseUrl: 'https://example.com',\n  onProgress: (completed, total, path) =\u003e {\n    console.log(`[${completed}/${total}] ${path}`);\n  },\n});\n\nconsole.log(`Prerendered ${result.success} routes in ${result.totalTime}ms`);\n```\n\n### Dynamic Route Parameters\n\n```typescript\nconst result = await prerenderRoutes({\n  routes: [\n    '/',\n    '/about',\n    {\n      path: '/blog/:slug',\n      getParams: async () =\u003e {\n        // Fetch slugs from CMS or database\n        const posts = await fetchBlogPosts();\n        return posts.map(post =\u003e ({ slug: post.slug }));\n      },\n    },\n  ],\n  // ...\n});\n```\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `NODE_ENV` | Environment mode | `development` |\n| `PORT` | Server port | `4000` |\n| `HOST` | Server hostname | `localhost` |\n| `BROWSER_DIST_FOLDER` | Browser dist path | Auto-detected |\n| `SERVER_DIST_FOLDER` | Server dist path | Auto-detected |\n\n## Performance Tips\n\n1. **Enable caching** in production for frequently accessed pages\n2. **Use prerendering** for static content that doesn't change often\n3. **Set appropriate cache headers** for static assets\n4. **Use `clientOnlyRoutes`** for pages that don't benefit from SSR\n5. **Monitor render times** using the `X-Render-Time` response header\n\n## Comparison with Express-based SSR\n\n| Feature | @pegasusheavy/ngx-bun | Express SSR |\n|---------|-------------------|-------------|\n| Cold Start | ~50ms | ~200ms |\n| Memory Usage | Lower | Higher |\n| Requests/sec | Higher | Lower |\n| Bundle Size | Smaller | Larger |\n| Native TypeScript | ✅ | ❌ |\n\n## Troubleshooting\n\n### \"Could not find index.html\"\n\nMake sure you've built the browser application first:\n\n```bash\nng build\n```\n\n### \"Server bootstrap not found\"\n\nEnsure `main.server.ts` exists and exports a bootstrap function:\n\n```typescript\n// src/main.server.ts\nimport { bootstrapApplication } from '@angular/platform-browser';\nimport { AppComponent } from './app/app.component';\nimport { config } from './app/app.config.server';\n\nconst bootstrap = () =\u003e bootstrapApplication(AppComponent, config);\nexport default bootstrap;\n```\n\n### Hydration Mismatch Errors\n\nEnsure your components handle server/browser differences:\n\n```typescript\nimport { isPlatformBrowser } from '@angular/common';\nimport { PLATFORM_ID, inject } from '@angular/core';\n\n@Component({...})\nexport class MyComponent {\n  private platformId = inject(PLATFORM_ID);\n\n  ngOnInit() {\n    if (isPlatformBrowser(this.platformId)) {\n      // Browser-only code\n    }\n  }\n}\n```\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nMIT © [Pegasus Heavy Industries](https://github.com/pegasusheavy)\n\n## Support\n\n- 📖 [Documentation](https://github.com/pegasusheavy/ngx-bun#readme)\n- 🐛 [Issue Tracker](https://github.com/pegasusheavy/ngx-bun/issues)\n- 💬 [Discussions](https://github.com/pegasusheavy/ngx-bun/discussions)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  Made with ❤️ for the Angular community\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquinnjr%2Fngx-bun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquinnjr%2Fngx-bun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquinnjr%2Fngx-bun/lists"}