FastBoot Express Middleware

Common errors

• Error: Cannot find module 'fastboot-express-middleware'

  cause The package `fastboot-express-middleware` is not installed or not resolvable in your project.
  fix Run `npm install fastboot-express-middleware` or `yarn add fastboot-express-middleware` in your project directory.

• ENOENT: no such file or directory, stat '/path/to/dist'

  cause The `distPath` provided to the `fastbootMiddleware` function does not point to a valid Ember application build directory, or the Ember application has not been built yet.
  fix Ensure your Ember application has `ember-cli-fastboot` installed and run `ember build`. Then, verify that the `distPath` option in your middleware configuration correctly points to the `dist` folder of your built Ember app.

• TypeError: app.get is not a function

  cause This error indicates that `app` is not an Express application instance, or that `express` was not properly imported/initialized.
  fix Ensure you have `const express = require('express');` and `let app = express();` correctly set up before using `app.get` or `app.use`.

Warnings

• breaking Version 3.0.0 dropped support for Node.js 4, 6, 8, 9, 11, and 13. Ensure your Node.js environment is 12.*, 14.*, or >=16.
  Fix: Upgrade Node.js to a supported version (12.*, 14.*, or >=16) or pin `fastboot-express-middleware` to a version prior to 3.0.0.
• breaking Version 3.0.0 updated its internal `fastboot` dependency to `fastboot@3.1.0`. This might introduce breaking changes from the underlying `fastboot` package itself if your Ember app relies on specific older FastBoot behaviors or APIs.
  Fix: Review the changelog for `fastboot@3.1.0` and `ember-cli-fastboot` for any potential incompatibilities with your Ember application. Test thoroughly after upgrading.
• gotcha When `resilient: true` is enabled, errors during rendering will result in an HTTP 200 status code and an empty HTML page. While subsequent error handling middleware will still be called via `next(err)`, you *cannot* alter the HTTP response within these post-FastBoot middleware because FastBoot has already sent a response.
  Fix: If you need to customize error responses, handle errors *before* the `fastbootMiddleware` or disable `resilient` mode to allow 500 status codes for render errors.
• gotcha For the middleware to function correctly, your Ember application must be built using `ember-cli-fastboot` and the `distPath` option must point to the resulting `dist` directory. This is not a runtime dependency but a prerequisite for your Ember app.
  Fix: Ensure `ember-cli-fastboot` is installed in your Ember project and run `ember build` before deploying your Express application. Verify `distPath` in your middleware configuration is correct.

Install

• npm install fastboot-express-middleware npm
• yarn add fastboot-express-middleware yarn
• pnpm add fastboot-express-middleware pnpm

Imports

• fastbootMiddleware
  wrong:

  import fastbootMiddleware from 'fastboot-express-middleware';

  correct:

  const fastbootMiddleware = require('fastboot-express-middleware');

  The package is primarily CommonJS. While Node.js allows `import` for CJS modules, the documented and most reliable approach is `require`.
• FastBoot

  const FastBoot = require('fastboot');

  When passing a custom FastBoot instance, import `FastBoot` directly from the `fastboot` package, not from `fastboot-express-middleware`.

Quickstart

This quickstart sets up a basic Express server that serves static assets from an Ember app's `dist` directory and then uses `fastboot-express-middleware` to render Ember applications on all remaining routes, demonstrating a minimal SSR setup.

const express = require('express');
const fastbootMiddleware = require('fastboot-express-middleware');
const path = require('path');

// IMPORTANT: Replace '/path/to/your/ember-app/dist' with the actual path
// after running 'ember build'. For example, if your Express app is in the
// root and your Ember app is in a subdirectory named 'my-ember-app',
// this path might be path.join(__dirname, '..', 'my-ember-app', 'dist');
const distPath = process.env.EMBER_APP_DIST_PATH || path.join(__dirname, 'dist'); 

let app = express();

// Serve static assets from the Ember app's 'dist' folder
app.use(express.static(distPath));

// Apply the FastBoot middleware for all routes
app.get('/*', fastbootMiddleware(distPath));

const PORT = process.env.PORT || 3000;
app.listen(PORT, function () {
  console.log(`FastBoot app listening on port ${PORT}! Serving from: ${distPath}`);
});