Common Migration Issues

CommonJS and ESM incompatibility

Although an application may bundle JS modules successfully it can still have errors with them at runtime. Page Kit uses more recent versions of Babel and Webpack which are stricter than older versions and default to assuming ESM syntax instead of CJS.

Error: exports is not defined

The module was detected as an ECMAScript module but later tried to assign module.exports or exports[prop] which are CommonJS. Find the module and refactor it to use only one module syntax.

ReferenceError: x is not defined

This is commonly caused when using require() to load an ESM module then referencing its default export without first accessing the default property. Refactor the code to reference the default property, e.g. const foo = require('module').default.

---

There is a project board to track CommonJS and ESM fixes here: https://github.com/Financial-Times/dotcom-page-kit/projects/1

References to (not obviously) n-ui properties

For apps using n-ui there are a number of properties which can be added to a request in order to configure some internals. Some are obviously part of n-ui (e.g. response.locals.nUiConfig) but others aren't. Below is a list of properties which are specific to n-ui and should be removed or refactored to use the Page Kit equivalent.

Stylesheet management

These can usually be removed as Page Kit does not provive any tools to split CSS. However, if your app does generate multiple stylesheets the assets middleware can be used to locate those files.

// n-ui
response.locals.stylesheets.inline = ['head', 'article'];
response.locals.stylesheets.lazy = ['main'];

// Page Kit assets middleware
const stylesheets = [
  response.assets.loader.getPublicURL('head.css'),
  response.assets.loader.getPublicURL('article.css')
];

const asyncStylesheets = response.assets.loader.getPublicURL('main.css');

<Shell stylesheets={stylesheets} asyncStylesheets={asyncStylesheets} />