Origami npm announcement and guides on how to migrate products#

Posted on 1 July 2021 by Origami.

TL;DR: We have released new versions of Origami components which bring full NPM support and drops support for Bower. This post explains the changes and how to migrate products to the new version.

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:

• Aligning our front-end practices with those now most commonly used across the company and the wider industry, which should help the onboarding of new software engineering hires.
• Origami components can now make use of the 1.6 million packages which are on the NPM registry.
• Origami components will be able to use modern tooling instead of the Origami team having to build bespoke tooling ourselves.
• Services such as Snyk, Dependabot, and Renovate will be able to work for the Origami dependencies a project has.

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:

• Origami Build Service: Follow this guide if your project uses the Origami Build Service.
• Bower: Follow this guide if your project installs components with Bower.
• Beta NPM: Follow this guide if your project already installs Origami components via NPM, these were experimental releases which were published to Bower and NPM.

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. Check your project builds Sass using Dart Sass, the canonical version of Sass, which is now required by Origami components – LibSass and Node Sass were deprecated in 2020.
4. Now you’re ready to do the NPM migration.
5. 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.
6. Clean the directory of node_modules and any built artefacts
7. 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.
8. If there are still dependencies declared in the bower.json file, try and find the corresponding package on the NPM registry.
9. Remove the bower.json file and .bowerrc file if it exists. E.G. rm -f .bowerrc bower.json
10. Remove the bower_components directory. rm -rf bower_components
11. Remove bower from the package.json file. E.G. npm uninstall bower
12. Update the Sass compiler’s includePath configuration to include node_modules and remove bower_components.
13. Update the Origami Sass imports to include the @financial-times namespace. E.G. @import 'o-icons/main'; becomes @import '@financial-times/o-icons/main';
    1. Note: Although we don’t recommend it, you may also add node_modules/@financial-times to your compiler’s includePath configuration. This will resolve Sass published under @financial-times without specifying a namespace. We don’t recommend this because it will require all dependent projects do the same. However, this step is required temporarily if your team is not updating to the latest version of Origami components on npm.
14. 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';
15. 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:

• This google spreadsheet, which contains your projects that are using Origami via Bower.
• The associated entry in the Risk Register which is linked to all the affected systems that we know of.

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

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: