{"id":26728335,"url":"https://github.com/friedemannsommer/astro-node-fastify","last_synced_at":"2026-02-17T01:12:43.560Z","repository":{"id":243703638,"uuid":"812071955","full_name":"friedemannsommer/astro-node-fastify","owner":"friedemannsommer","description":"Fast, opinionated Node.js adapter for Astro SSR using Fastify with built-in compression and caching.","archived":false,"fork":false,"pushed_at":"2026-02-10T23:28:11.000Z","size":30300,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-11T02:28:25.314Z","etag":null,"topics":["astro","astro-adapter","fastify","nodejs"],"latest_commit_sha":null,"homepage":"https://friedemannsommer.github.io/astro-node-fastify/","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/friedemannsommer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"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}},"created_at":"2024-06-07T22:34:48.000Z","updated_at":"2026-02-10T23:24:31.000Z","dependencies_parsed_at":"2024-06-13T04:42:02.082Z","dependency_job_id":"34ef54bc-7a18-4e4c-9d0b-e3d55f6c8c62","html_url":"https://github.com/friedemannsommer/astro-node-fastify","commit_stats":null,"previous_names":["friedemannsommer/astro-node-fastify"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/friedemannsommer/astro-node-fastify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedemannsommer%2Fastro-node-fastify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedemannsommer%2Fastro-node-fastify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedemannsommer%2Fastro-node-fastify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedemannsommer%2Fastro-node-fastify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/friedemannsommer","download_url":"https://codeload.github.com/friedemannsommer/astro-node-fastify/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedemannsommer%2Fastro-node-fastify/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29528487,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T00:57:22.232Z","status":"ssl_error","status_checked_at":"2026-02-17T00:54:25.811Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["astro","astro-adapter","fastify","nodejs"],"created_at":"2025-03-27T22:23:15.452Z","updated_at":"2026-02-17T01:12:43.551Z","avatar_url":"https://github.com/friedemannsommer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Astro Node.js Fastify\n\n\u003e This adapter uses the [Fastify](https://fastify.dev/) web framework which allows [Astro](https://astro.build/) to\n\u003e deploy SSR sites to Node.js targets.\n\u003e It also compresses asset and SSR responses by default.\n\n[![CI](https://github.com/friedemannsommer/astro-node-fastify/actions/workflows/ci.yml/badge.svg)](https://github.com/friedemannsommer/astro-node-fastify/actions/workflows/ci.yml)\n![Node.js runtime support](https://img.shields.io/node/v/astro-node-fastify?style=flat)\n[![NPM Version](https://img.shields.io/npm/v/astro-node-fastify?style=flat)](https://www.npmjs.com/package/astro-node-fastify)\n\n## Table of contents\n\n\u003c!-- TOC --\u003e\n* [Astro Node.js Fastify](#astro-nodejs-fastify)\n  * [Table of contents](#table-of-contents)\n  * [Quickstart](#quickstart)\n  * [Usage](#usage)\n  * [Configuration Example](#configuration-example)\n  * [Configuration](#configuration)\n  * [Troubleshooting](#troubleshooting)\n    * [Common Issues and Solutions](#common-issues-and-solutions)\n      * [Compression Not Working](#compression-not-working)\n      * [404 Errors for Assets in Dot Files/Directories](#404-errors-for-assets-in-dot-filesdirectories)\n      * [Static Assets Not Caching Properly](#static-assets-not-caching-properly)\n      * [Server Running Out of Memory](#server-running-out-of-memory)\n      * [Issues Behind a Reverse Proxy](#issues-behind-a-reverse-proxy)\n    * [Getting Help](#getting-help)\n\u003c!-- TOC --\u003e\n\n## Quickstart\n\n1. Install via the package manager of your choice\n    * Example via NPM: `npm i --save-prod astro-node-fastify`\n    * Or via\n      the [Astro CLI](https://docs.astro.build/en/guides/integrations-guide/#automatic-integration-setup):\n      `astro add astro-node-fastify`\n2. Build your site\n3. Either start a [preview](https://docs.astro.build/en/reference/cli-reference/#astro-preview) or\n   the [standalone entry](https://docs.astro.build/en/reference/configuration-reference/#buildserverentry).\n\n## Usage\n\nAdd this package as a runtime dependency using your preferred package manager.\n\nOnce installed, you can customize various aspects of your Astro application through configuration options.\nYou can specify which assets should be pre-compressed to improve load times,\ndefine appropriate cache headers for files in your Astro \"public\" directory,\nand set default response headers that will apply to all server-side rendered responses.\n\nFor instance, you might configure specific cache control settings for static assets or enable particular compression\nalgorithms like gzip or brotli.\n\n## Configuration Example\n\n\u003cdetails\u003e\n\u003csummary\u003eShow Astro config example\u003c/summary\u003e\n\n```javascript\n// astro.config.mjs\nimport {defineConfig} from 'astro/config';\nimport nodeFastify from 'astro-node-fastify';\n\nexport default defineConfig({\n    output: 'server',\n    adapter: nodeFastify({\n        // Controls whether static assets are pre-compressed at build time (true)\n        // or compressed dynamically at runtime (false).\n        // Pre-compressing improves performance by avoiding on-the-fly compression.\n        preCompressed: true,\n\n        // Specifies which compression algorithms the server should support.\n        // Browsers will choose the best available algorithm they support\n        // based on the Accept-Encoding header.\n        supportedEncodings: ['br', 'gzip'],\n\n        // Configure cache headers for static assets to optimize performance\n        // and reduce server load by leveraging browser and CDN caching.\n        cache: {\n            // Set maximum time (in seconds) that browsers should cache assets\n            // 604,800 seconds = 7 days\n            maxAge: 604800,\n\n            // Allow CDNs to serve stale content while revalidating in background\n            // 86,400 seconds = 24 hours\n            staleWhileRevalidate: 86400,\n\n            // Allow serving stale content if origin server errors occur\n            // 86,400 seconds = 24 hours\n            staleIfError: 86400\n        },\n\n        // Set HTTP headers that will be automatically included in responses\n        defaultHeaders: {\n            // Headers for dynamically generated server-side rendered pages\n            ssr: {\n                // Prevents MIME-type sniffing security issues\n                'X-Content-Type-Options': 'nosniff',\n\n                // Prevents your site from being embedded in iframes on other domains\n                // protecting against clickjacking attacks\n                'X-Frame-Options': 'SAMEORIGIN'\n            },\n\n            // Headers for static assets served from the public directory\n            asset: {\n                // Prevents MIME-type sniffing security issues\n                'X-Content-Type-Options': 'nosniff'\n            }\n        },\n\n        // Configure the underlying Fastify server behavior\n        server: {\n            // Enables HTTP request logging for monitoring and debugging\n            accessLogging: true,\n\n            // Specifies which IP addresses should be trusted when behind proxies\n            // Important for preserving correct client IP addresses in logs and for\n            // security features that depend on accurate client identification\n            trustProxy: ['127.0.0.1', '::1']\n        },\n\n        // Configure which files and directories starting with a dot (.) can be served.\n        // The following example shows the default configuration - '/.well-known/' is\n        // already included by default, so you only need to specify this option if you\n        // want to add additional paths or remove the default.\n        dotPrefixes: ['/.well-known/']\n    })\n});\n```\n\u003c/details\u003e\n\n## Configuration\n\nThe configuration documentation can be found here:\n[https://friedemannsommer.github.io/astro-node-fastify/](https://friedemannsommer.github.io/astro-node-fastify/development/interfaces/_internal_.UserOptions.html).\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n#### Compression Not Working\n\n**Symptoms**: Assets aren't being compressed as expected, or browsers aren't receiving compressed content.\n\n**Solutions**:\n\n- Make sure you haven't disabled `preCompressed` if you want build-time compression\n- Check that your `supportedEncodings` includes the compression algorithms you expect (`br` and/or `gzip`)\n- Verify that the client sending requests includes the appropriate `Accept-Encoding` header\n\n#### 404 Errors for Assets in Dot Files/Directories\n\n**Symptoms**: Assets under directories that start with a dot (e.g., `.github/`) are inaccessible.\n\n**Solutions**:\n\n- Add the path prefix to the `dotPrefixes` option (e.g., `['/.custom-directory/', '/.other-directory/']`)\n- Note that by default only `/.well-known/` is allowed\n\n#### Static Assets Not Caching Properly\n\n**Symptoms**: Browsers repeatedly download the same static assets instead of using cached versions.\n\n**Solutions**:\n\n- Ensure your `cache` configuration is correctly set with appropriate values\n- Check if other headers in your deployment environment (like CDN settings) might be overriding your cache configuration\n- Verify that the `Cache-Control` header is being set correctly using browser developer tools\n\n#### Server Running Out of Memory\n\n**Symptoms**: Server crashes with memory-related errors under load.\n\n**Solutions**:\n\n- Consider setting `preCompressed: true` (default) to avoid runtime compression overhead\n- If your site has huge assets, you might need to allocate more memory to your Node.js process\n\n#### Issues Behind a Reverse Proxy\n\n**Symptoms**: Client IP addresses are incorrect, or some security features don't work properly.\n\n**Solutions**:\n\n- Configure the `server.trustProxy` setting to properly identify trusted proxy servers\n- Ensure your reverse proxy (nginx, Apache, etc.) is correctly configured to pass the required headers:\n    - `X-Forwarded-For`: Original client IP address\n    - `X-Forwarded-Proto`: Original protocol (http/https)\n    - `X-Forwarded-Host`: Original host requested by the client\n    - `X-Real-IP`: Alternative client IP header used by some proxies\n\n### Getting Help\n\nIf you encounter issues not covered here:\n\n1. Check the [GitHub Issues](https://github.com/friedemannsommer/astro-node-fastify/issues) to see if your problem has\n   been reported\n2. Before opening a new issue:\n    - Make sure the issue is related to this adapter specifically, not your Astro project or deployment environment\n    - Create a minimal reproduction that isolates the problem to this adapter's functionality\n    - Include your adapter configuration and relevant environment details (Node.js version, OS, etc.)\n\n**Support Scope**:\n\n- ✅ Issues with the adapter's core functionality (compression, serving files, caching, etc.)\n- ✅ Documentation clarifications or improvements\n- ✅ Feature requests specific to the adapter\n- ❌ General Astro project issues not specific to this adapter\n- ❌ Deployment environment setup (AWS, Vercel, etc.)\n- ❌ Custom server configurations beyond this adapter's API\n\nFor general Astro help, please use [Astro's Discord](https://astro.build/chat)\nor [Stack Overflow](https://stackoverflow.com/questions/tagged/astro).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriedemannsommer%2Fastro-node-fastify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffriedemannsommer%2Fastro-node-fastify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriedemannsommer%2Fastro-node-fastify/lists"}