Ember FastBoot App Server

Common errors

• Error: Cannot find module 'fastboot-app-server'

  cause Attempting to use ES module `import` syntax (`import FastBootAppServer from 'fastboot-app-server'`) in a CommonJS context, or incorrect package installation/path.
  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`.

• TypeError: app.buildSandboxGlobals is not a function

  cause Calling `buildSandboxGlobals` or similar methods on an incorrect object, or passing an invalid type to the server options.
  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.

• Error: EMFILE: too many open files, watch

  cause Node.js file watcher limit reached, often due to many files in the `distPath` or multiple workers monitoring the same directory.
  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.

Warnings

• breaking 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.
  Fix: Upgrade your Node.js runtime to version 14 or higher (e.g., 14.*, >=16) before deploying FastBoot App Server v4+.
• breaking Version 4.0.0 removed deprecated implicit injections. Any code relying on these older injection patterns will break.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install fastboot-app-server npm
• yarn add fastboot-app-server yarn
• pnpm add fastboot-app-server pnpm

Imports

• FastBootAppServer
  wrong:

  import { FastBootAppServer } from 'fastboot-app-server';

  correct:

  const FastBootAppServer = require('fastboot-app-server');

  The primary entry point for the FastBoot App Server. Examples consistently use CommonJS `require()`.
• ExpressHTTPServer

  const ExpressHTTPServer = require('fastboot-app-server/src/express-http-server');

  Used for customizing the underlying HTTP server with Express. Note the explicit path to `src/`.
• MyCustomExpressServer (example)
  wrong:

  import { MyCustomExpressServer } from 'my-custom-express-server';

  correct:

  class MyCustomExpressServer extends ExpressHTTPServer { /* ... */ }

  Illustrates extending the provided ExpressHTTPServer for advanced customization, not a direct import from the package root.

Quickstart

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.

const FastBootAppServer = require('fastboot-app-server');

const MY_GLOBAL = 'MY GLOBAL';

let server = new FastBootAppServer({
  distPath: 'dist',
  gzip: true, // Optional - Enables gzip compression.
  host: '0.0.0.0', // Optional - Sets the host the server listens on.
  port: 4000, // Optional - Sets the port the server listens on (defaults to the PORT env var or 3000).
  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"
    return Object.assign({}, defaultGlobals, { GLOBAL_VALUE: MY_GLOBAL });
  },
  log: true, // Optional - Specifies whether the server should use its default request logging. Useful for turning off default logging when providing custom logging middlewares
  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.
});

server.start();