Upgrading from 0.3.x to 0.4.x

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

Upgrade n-gage

Please ensure the app is using n-gage >= 4.0.0-beta.2 and n-heroku-tools >= v8.4.0 which support uploading the compressed assets generated by this version of Page Kit.

Layout component changes

• The header option has split into two separate options, headerVariant and headerComponent. If the app sets a built-in variant (either "simple" or "large-logo") you must update the option to headerVariant. If the app is providing a custom header component you need to refactor to use the headerComponent option.

• The footer option has been split into two separate options, footerVariant and footerComponent. If the app sets a built-in variant (either "simple" or "legal") you must update the option to footerVariant. If the app is providing a custom footer component you need to refactor to use the footerComponent option.

Header component changes

• The disableSticky option has been replaced with the showStickyHeader option which is enabled by default. To disable the sticky header either configure this option by passing headerOptions to the layout component or by setting the showStickyHeader prop when integrating the header component directly.

Optional: Sharing global styles

Please hold off from implementing this. Due to the ongoing Origami component upgrade work there are a lot of other style-related changes happening.

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-foundation at v3.2.0 or greater:

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

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

   - @import '@financial-times/dotcom-ui-layout/styles';
   + @import 'n-ui-foundations/mixins';

   Please note that you may need to add n-ui-foundations as a Bower dependency of the app.

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={[
   +       ...assets.loader.getStylesheetURLsFor('page-kit-layout-styles'),
           ...assets.loader.getStylesheetURLsFor('styles')
       ]}
   />