Origami Frontend Components & Services

Origami npm announcement and guides on how to migrate products

Posted on by Origami.

We have completed our migration of Origami components from Bower to the NPM registry (see January’s announcement). Component releases on Bower are now deprecated and we recommend all products migrate to the new implementation to keep up-to-date with future releases to Origami.

The FT Bower Registry has now been placed into a maintenance only mode for 12 months, until 1st July 2022, when we will look to decommission the service completely.

Moving Origami from Bower to NPM provides many benefits, such as:

We’re already seeing the benefits with our work on a new autocomplete Origami component, which has been requested by several different FT products. By making this an npm-only component, we’ve been able to benefit from autocomplete packages which already exist on NPM, such as the one made by Gov UK named accessible-autocomplete. This has greatly reduced the amount of code we would have had to write ourselves and meant we could create a prototype for products to trial in a shorter turnaround then previously possible.

What has changed for Origami users?

The code for Origami components has remained largely the same, aiming to make the migration simpler for our users. The one change we had to make was making the package name for all components now start with @financial-times/, as they are published under the financial-times namespace on npm. This change means that when importing the javascript and/or sass of a component, you will need to prepend @financial-times/ to the imported package name.

If using Origami components via NPM, it is required to use NPM version 7, this is because version 7 ensures that Origami components are only installed once and no conflicting versions are installed. Origami components do not support using older versions of NPM.

Those changes don’t affect projects which include Origami components using the Origami Build Service, but there is a new version of the Origami Build Service projects must upgrade to.

See the below migration guides for more details.

Migration Guides

The following 3 guides show how to migrate to the new npm-only Origami component releases depending on how your project currently includes components:

Using Origami via Origami Build Service

Use the Origami Build Service URL Updater to guide you through the following process.

  1. Run your project locally in its current state and confirm it is still working correctly.
  2. Check your Origami Build Service URL requests the latest major Bower release of each component:
    • If your project already requests the latest Bower release of each component no code changes are required. Otherwise;
    • If your project is using outdated component releases, follow the component migration guides to update to the latest major Bower release.
  3. Run your project locally and confirm it is still working correctly. Now you’re ready to do the NPM migration.
  4. Update your Origami Build Service urls to use the Origami Build Service v3 API instead of v2.
  5. Run your project locally and confirm it is still working correctly.

Your migration to npm Origami components is finished! 🎉

Using Origami via Bower

  1. Run the project locally in its current state.
  2. Check your project installs the latest major Bower release of each component. If your project is using outdated component releases, follow the component migration guides to update to the latest major Bower release.
  3. Now you’re ready to do the NPM migration.
  4. If the project is not using NPM version 7:
    1. Clean the directory of node_modules and any built artefacts
    2. Switch to NPM version 7 and install the dependencies
    3. Confirm the project is still working correctly - If it is not working, try deleting the package-lock.json and/or npm-shrinkwrap.json files and run npm install again. There is a known issue with upgrading to NPM version 7 and those files becoming corrupted.
  5. Clean the directory of node_modules and any built artefacts
  6. Install all origami dependencies as npm dependencies and remove them from the bower.json file. All the components are under the @financialt-times namespace on NPM. I.E. To install o-table, npm install @financial-times/o-table.
  7. If there are still dependencies declared in the bower.json file, try and find the corresponding package on the NPM registry.
  8. Remove the bower.json file and .bowerrc file if it exists. E.G. rm -f .bowerrc bower.json
  9. Remove the bower_components directory. rm -rf bower_components
  10. Remove bower from the package.json file. E.G. npm uninstall bower
  11. Update the Sass compiler’s includePath configuration to include node_modules and remove bower_components, then either:
    • Add an additional path node_modules/@financial-times to resolve Sass published under @financial-times without specifying a namespace. Or;
    • Update the Origami Sass imports to include the @financial-times namespace. E.G. @import 'o-icons/main'; becomes @import '@financial-times/o-icons/main';
  12. Update your Origami JavaScript imports to include the @financial-times namespace. E.G. import oTracking from 'o-tracking'; becomes import oTracking from '@financial-times/o-tracking'; and import 'o-layout'; becomes import '@financial-times/o-layout';
  13. Run the project locally and confirm it is still working correctly

Your migration to npm Origami components is finished! 🎉

Using Origami via beta NPM

If your project already installs Origami components via NPM, these were experimental releases which were published to Bower and NPM.

  1. Run your project locally in its current state and confirm it is still working correctly
  2. Check your project installs the latest major version that was released to Bower of each component. If your project is using outdated component releases, follow the component migration guides to update to the latest major release that was Bower-compatible.
  3. If your project is not using NPM version 7:
    1. Clean the directory of node_modules and any built artefacts
    2. Switch to NPM version 7 and install the dependencies
      1. Confirm your project is still working correctly - If it is not working, try deleting the package-lock.json and/or npm-shrinkwrap.json files and run npm install again. There is a known issue with upgrading to NPM version 7 and those files becoming corrupted.
  4. Clean the directory of node_modules and any built artefacts
  5. Upgrade to the latest major versions of any Origami components you are using
  6. If using lockspot or is-origami-flat, these should be removed as they are no longer needed when using NPM version 7. npm uninstall lockspot is-origami-flat
  7. Run your project locally and confirm it is still working correctly

Your migration to npm Origami components is finished! 🎉

Tracking migrations

We can detect when the relevant repos have been updated to remove Bower. Using that data, we will update:

Below is a breakdown of how many systems and repositories will need to be migrated, split by group:

Group Systems to migrate Repositories to migrate
Customer Products 25 74
FT Core 2 10
FT Professional 4 6
Internal Products 4 2
Operations & Reliability 3 41

Last Bower Releases

Make sure your project has upgraded to the latest component released to Bower before attempting to migrate to the NPM-only releases. Here is a table of Bower component releases for reference:

Project Last Major Bower Release Migration Guide
o-autoinit 2.0.0 o-autoinit migration guide
o-banner 3.0.0 o-banner migration guide
o-big-number 2.0.0 o-big-number migration guide
o-brand 3.0.0 o-brand migration guide
o-buttons 6.0.0 o-buttons migration guide
o-colors 5.0.0 o-colors migration guide
o-cookie-message 5.0.0 o-cookie-message migration guide
o-date 4.0.0 o-date migration guide
o-editorial-layout 1.0.0 o-editorial-layout migration guide
o-editorial-typography 1.0.0 o-editorial-typography migration guide
o-errors 4.0.0 o-errors migration guide
o-expander 5.0.0 o-expander migration guide
o-fonts 4.0.0 o-fonts migration guide
o-fonts-assets 1.0.0 o-fonts-assets migration guide
o-footer 7.0.0 o-footer migration guide
o-footer-services 3.0.0 o-footer-services migration guide
o-forms 8.0.0 o-forms migration guide
o-ft-affiliate-ribbon 4.0.0 o-ft-affiliate-ribbon migration guide
ftdomdelegate 4.0.0 ftdomdelegate migration guide
o-grid 5.0.0 o-grid migration guide
o-header 8.0.0 o-header migration guide
o-header-services 4.0.0 o-header-services migration guide
o-icons 6.0.0 o-icons migration guide
o-labels 5.0.0 o-labels migration guide
o-layers 2.0.0 o-layers migration guide
o-layout 4.0.0 o-layout migration guide
o-lazy-load 2.0.0 o-lazy-load migration guide
o-loading 4.0.0 o-loading migration guide
o-message 4.0.0 o-message migration guide
o-meter 2.0.0 o-meter migration guide
o-normalise 2.0.0 o-normalise migration guide
o-overlay 3.0.0 o-overlay migration guide
o-quote 4.0.0 o-quote migration guide
o-share 7.0.0 o-share migration guide
o-spacing 2.0.0 o-spacing migration guide
o-stepped-progress 2.0.0 o-stepped-progress migration guide
o-syntax-highlight 3.0.0 o-syntax-highlight migration guide
o-table 8.0.0 o-table migration guide
o-tabs 5.0.0 o-tabs migration guide
o-teaser 5.0.0 o-teaser migration guide
o-teaser-collection 3.0.0 o-teaser-collection migration guide
o-toggle 2.0.0 o-toggle migration guide
o-tooltip 4.0.0 o-tooltip migration guide
o-topper 3.0.0 o-topper migration guide
o-tracking 3.0.0 o-tracking migration guide
o-typography 6.0.0 o-typography migration guide
o-utils 1.0.0 o-utils migration guide
o-viewport 4.0.0 o-viewport migration guide
o-visual-effects 3.0.0 o-visual-effects migration guide