Prember (Pre-Render Ember)

Common errors

• Error: Prember encountered an error during prerendering: No FastBoot manifest found

  cause `ember-cli-fastboot` is not installed or configured correctly, or the Ember CLI build process failed to generate the necessary FastBoot assets.
  fix Ensure `ember-cli-fastboot` is installed (`npm install --save-dev ember-cli-fastboot`) and that your Ember app builds successfully with FastBoot enabled before attempting a Prember build.

• Build failed. The Broccoli Plugin 'Prember' failed with: Error: Cannot find module '...' 

  cause A module dependency required by your Ember app during FastBoot rendering is missing or not correctly bundled for the FastBoot environment.
  fix Check your `package.json` for missing `dependencies` (not `devDependencies`), especially for modules used in `app/initializers` or `app/instance-initializers`. Ensure any Node.js-specific dependencies are correctly configured for FastBoot or mocked if they are browser-only.

• Node.js v14.x is not supported by prember@2.x.x

  cause Attempting to run `prember` version 2.x.x (or higher) with an incompatible Node.js version.
  fix Upgrade your Node.js version to 16 or higher (`nvm install 16 && nvm use 16`) as `prember` v2.x.x requires Node.js >= 16.

• The 'prember' configuration option is missing 'urls'.

  cause The `prember` configuration object in `ember-cli-build.js` does not specify any URLs to prerender.
  fix Add an array of URLs to the `prember` configuration, e.g., `prember: { urls: ['/', '/my-page'] }`.

Warnings

• breaking Dropped support for Node.js versions prior to 16.
  Fix: Ensure your Node.js environment is version 16 or higher. Update Node.js using `nvm install 16` or similar version manager, then `nvm use 16`.
• breaking Dropped support for Node.js versions prior to 8.
  Fix: Update your Node.js environment to version 8 or higher. For versions >= 2.0.0, Node.js >= 16 is required.
• breaking Changes in how `config/fastboot.js` is applied.
  Fix: Review your `config/fastboot.js` file and ensure its configuration aligns with how `ember-cli-fastboot` applies it, as Prember v2.0.0 now follows the same methodology. This may affect service worker registrations or global FastBoot configuration.
• gotcha FastBoot instance recycling for long builds.
  Fix: Prember now recycles the FastBoot instance after 1000 requests to mitigate potential memory leaks during very large prerendering builds. While generally an enhancement, monitor memory usage for extremely complex routes or very large numbers of prerendered URLs, as edge cases might still exist depending on app complexity.
• gotcha URLs not prerendering or showing incorrect content.
  Fix: Verify that the URLs specified in `prember.urls` are valid routes in your Ember application and are accessible via FastBoot. Ensure any dynamic data needed for those routes is available during the build process (e.g., through static mocks or data available at build time).
• gotcha Web server configuration for prerendered files.
  Fix: After building, configure your web server (e.g., Nginx, Apache, Netlify) to correctly serve the prerendered `index.html` files for the specified paths (e.g., `/about` should serve `dist/about/index.html`). The default `index.html` in `dist/` becomes `_empty.html` and a new `index.html` at the root contains the prerendered content for `/`.

Install

• npm install prember npm
• yarn add prember yarn
• pnpm add prember pnpm

Imports

• Prember Configuration Object
  wrong:

  import { prember } from 'prember';

  correct:

  let app = new EmberApp(defaults, { prember: { urls: ['/', '/about'] } });

  Prember is an Ember CLI addon. Its functionality is primarily configured via a `prember` key within the options object passed to the `EmberApp` constructor in `ember-cli-build.js`. Direct JavaScript `import` or `require` statements for symbols from `prember` are not used in application code.
• prember.urls

  prember: { urls: ['/', '/contact'] }

  The `urls` property within the `prember` configuration object defines the specific routes that Prember should prerender. This is the most common way to specify static pages. The value should be an array of strings representing paths.
• EmberApp Addon Options

  let app = new EmberApp(defaults, { /* ... addon options ... */ });

  Prember is enabled and configured by including its options directly within the `EmberApp` constructor's second argument (the options object) in `ember-cli-build.js`. This is the standard pattern for Ember CLI addon configuration.

Quickstart

This quickstart demonstrates how to install `prember` and configure it in `ember-cli-build.js` to prerender a list of specified URLs during a production build.

const EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    // Configure prember to prerender specific URLs
    prember: {
      urls: [
        '/',          // The root path
        '/about',     // An example static page
        '/products/1',// An example dynamic path (ensure it resolves correctly)
        '/blog/latest',// Another example path
        '/contact-us' // A more descriptive path
      ]
    }
    // Other Ember CLI build options can go here
  });

  // Use `app.toTree()` to return the Broccoli tree for your app
  return app.toTree();
};

// To install the addons:
// npm install --save-dev ember-cli-fastboot prember

// To build the prerendered app:
// ember build --environment=production