Upgrading from 0.5.x to 0.6.x

This guide is suitable for most FT.com apps which have followed the n-ui to Page Kit migration guide.

Bump to Node v12

Before starting the migration to Page Kit v0.6.0 please ensure the application is running in production on Node v12.x.

Update the assets middleware

The dotcom-middleware-assets package has been replaced by the dotcom-middleware-asset-loader package.

1. Replace the dependency on the assets middleware to the new asset loader middleware in your application's package.json:

   - "@financial-times/dotcom-middleware-assets": "^0.5.0",
   + "@financial-times/dotcom-middleware-asset-loader": "^0.6.0",

2. Update the initialisation of the assets middleware to use the new package and change the publicPath option to include the absolute URL when run in production mode:

   - const assetsMiddleware = require('@financial-times/dotcom-middleware-assets');
   + const assetLoaderMiddleware = require('@financial-times/dotcom-middleware-asset-loader');
   
   app.use(
   -    assetsMiddleware.init({
   +    assetLoaderMiddleware.init({
           hostStaticAssets: !isProduction,
   -       publicPath: isProduction ? '/__assets/hashed/page-kit' : '/__dev/assets/<app-name>'
   +       publicPath: isProduction ? 'https://www.ft.com/__assets/hashed/page-kit' : '/__dev/assets/<app-name>'
       })
   );

3. Refactor all references to the asset loader in your application:

   - res.locals.assets.loader.getScriptURLsFor('scripts')
   + res.locals.assetLoader.getScriptURLsFor('scripts')

   Please note the resource hints API has been removed and there is no replacement.

Switch dom-loaded for ready-state

1. Install the ready-state package:

   npm i -D ready-state

2. Remove the old dom-loaded dependency from package.json:

   - "dom-loaded": "^1.2.0",
   + "ready-state": "^2.0.5",

3. Refactor the integration of dom-loaded to use the ready-state package:

   - import domLoaded from 'dom-loaded';
   + import readyState from 'ready-state';
   
   - domLoaded.then(() => {
   + readyState.dom.then(() => {
       ...
   });

Apply shared layout styles

The layout component styles can now be built as an individual entrypoint which has the benefit of improving long-term caching and potentially sharing the styles between applications. To enable this:

1. Install n-ui-foundations at v4.0.0 or greater:

   bower i -S n-ui-foundations@^4.0.0

2. Open the application's main stylesheet and update the following line:

   - @import '@financial-times/dotcom-ui-layout/styles';
   + $system-code: 'next-app-name';
   + @import 'n-ui-foundations/mixins';

3. Open the application's Page Kit build configuration and add the layout styles as an entry point:

   module.exports = {
       plugins: [...],
       settings: {
           build: {
               entry: {
                   scripts: './client/main.js',
                   styles: './client/main.scss',
   +               'page-kit-layout-styles': require.resolve('@financial-times/dotcom-ui-layout/styles.scss')
               }
           }
       }
   }

   Please note that the name of the entry point must be "page-kit-layout-styles" in order for the stylesheet to be reused between applications.

4. Add the generated stylesheet to the stylesheets option passed to the shell component:

   <Shell
       stylesheets={[
   +       ...res.locals.assetLoader.getStylesheetURLsFor('page-kit-layout-styles'),
           ...res.locals.assetLoader.getStylesheetURLsFor('styles')
       ]}
   />

   Please note the Page Kit styles must be first in the list of stylesheets.