{"id":10874,"library":"fastboot-app-server","title":"Ember FastBoot App Server","description":"fastboot-app-server is a dedicated application server designed for deploying and running Ember FastBoot applications in production environments. It provides robust capabilities for managing the lifecycle of an Ember app, including downloading new builds, automatically scaling across CPU cores using Node.js clustering, and seamlessly detecting and hot-reloading new application versions without downtime. The current stable version is 4.1.4. The project maintains a steady release cadence with frequent patch updates and less frequent major versions, with v4.0.0 released in early 2024. Key differentiators include its built-in extensibility, allowing developers to customize how app builds are downloaded (Downloader), how new versions are detected (Notifier), and even swap out the underlying HTTP server implementation (e.g., using Express) to integrate custom middleware or routing. It aims to simplify the operational aspects of server-side rendering Ember applications.","status":"active","version":"4.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/ember-fastboot/ember-cli-fastboot","tags":["javascript","ember","fastboot","server"],"install":[{"cmd":"npm install fastboot-app-server","lang":"bash","label":"npm"},{"cmd":"yarn add fastboot-app-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add fastboot-app-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime environment for the server. Specific versions are required, with older versions deprecated in major releases.","package":"node","optional":false},{"reason":"Core FastBoot engine for rendering Ember apps, a peer dependency managed internally.","package":"fastboot","optional":false}],"imports":[{"note":"The primary entry point for the FastBoot App Server. Examples consistently use CommonJS `require()`.","wrong":"import { FastBootAppServer } from 'fastboot-app-server';","symbol":"FastBootAppServer","correct":"const FastBootAppServer = require('fastboot-app-server');"},{"note":"Used for customizing the underlying HTTP server with Express. Note the explicit path to `src/`.","symbol":"ExpressHTTPServer","correct":"const ExpressHTTPServer = require('fastboot-app-server/src/express-http-server');"},{"note":"Illustrates extending the provided ExpressHTTPServer for advanced customization, not a direct import from the package root.","wrong":"import { MyCustomExpressServer } from 'my-custom-express-server';","symbol":"MyCustomExpressServer (example)","correct":"class MyCustomExpressServer extends ExpressHTTPServer { /* ... */ }"}],"quickstart":{"code":"const FastBootAppServer = require('fastboot-app-server');\n\nconst MY_GLOBAL = 'MY GLOBAL';\n\nlet server = new FastBootAppServer({\n  distPath: 'dist',\n  gzip: true, // Optional - Enables gzip compression.\n  host: '0.0.0.0', // Optional - Sets the host the server listens on.\n  port: 4000, // Optional - Sets the port the server listens on (defaults to the PORT env var or 3000).\n  buildSandboxGlobals(defaultGlobals) { // Optional - Make values available to the Ember app running in the FastBoot server, e.g. \"MY_GLOBAL\" will be available as \"GLOBAL_VALUE\"\n    return Object.assign({}, defaultGlobals, { GLOBAL_VALUE: MY_GLOBAL });\n  },\n  log: true, // Optional - Specifies whether the server should use its default request logging. Useful for turning off default logging when providing custom logging middlewares\n  chunkedResponse: true // Optional - Opt-in to chunked transfer encoding, transferring the head, body and potential shoeboxes in separate chunks. Chunked transfer encoding should have a positive effect in particular when the app transfers a lot of data in the shoebox.\n});\n\nserver.start();","lang":"javascript","description":"Demonstrates how to initialize and start a FastBoot App Server with common configuration options such as distPath, gzip, host, port, custom sandbox globals, logging, and chunked responses."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 14 or higher (e.g., 14.*, >=16) before deploying FastBoot App Server v4+.","message":"FastBoot App Server v4.0.0 and above no longer support Node.js v12. Ensure your production environment uses Node.js v14 or later. While the `engines` field in package.json might include Node 12, the official release notes for v4.0.0 explicitly state the removal of Node 12 support.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Review your Ember FastBoot app's code for implicit injections and update them to use explicit injection patterns supported by modern Ember versions. Refer to Ember FastBoot documentation for current best practices on dependency injection.","message":"Version 4.0.0 removed deprecated implicit injections. Any code relying on these older injection patterns will break.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"While currently documented, be aware that future versions might alter the internal path. Consider wrapping this import in your own module or monitoring release notes for changes to this pattern. For complex customizations, extending `FastBootAppServer` itself might be a more stable approach if the `src` path becomes an issue.","message":"When customizing the HTTP server, the `ExpressHTTPServer` class is imported from `fastboot-app-server/src/express-http-server`. Directly referencing `src` paths can be fragile across minor versions as internal directory structures are not part of the public API and may change.","severity":"gotcha","affected_versions":">=3.x"},{"fix":"Double-check that the `distPath` value in your server configuration (e.g., `fastboot-server.js`) accurately reflects the absolute or relative path to your Ember app's `dist` folder. Ensure the `dist` folder exists and contains the necessary FastBoot build artifacts.","message":"The `distPath` option must correctly point to the compiled `dist` directory of your Ember application. Misconfiguration will lead to the server being unable to locate and serve your application.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using CommonJS `require()` syntax (`const FastBootAppServer = require('fastboot-app-server');`) if your project is not configured for ESM. Also, verify `fastboot-app-server` is correctly installed in your `node_modules`.","cause":"Attempting to use ES module `import` syntax (`import FastBootAppServer from 'fastboot-app-server'`) in a CommonJS context, or incorrect package installation/path.","error":"Error: Cannot find module 'fastboot-app-server'"},{"fix":"Ensure `buildSandboxGlobals` is passed as an option during the `FastBootAppServer` constructor, not called directly. It should be a function that receives `defaultGlobals` and returns an object of additional globals.","cause":"Calling `buildSandboxGlobals` or similar methods on an incorrect object, or passing an invalid type to the server options.","error":"TypeError: app.buildSandboxGlobals is not a function"},{"fix":"Increase your system's `fs.inotify.max_user_watches` limit (Linux) or `kern.maxfiles` (macOS). Alternatively, for very large apps or complex deployments, consider disabling the server's default file watching mechanism if you have an external build deployment strategy.","cause":"Node.js file watcher limit reached, often due to many files in the `distPath` or multiple workers monitoring the same directory.","error":"Error: EMFILE: too many open files, watch"}],"ecosystem":"npm"}