Origami npm announcement and guides on how to migrate products
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.
- Run your project locally in its current state and confirm it is still working correctly.
- 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.
- Run your project locally and confirm it is still working correctly. Now you’re ready to do the NPM migration.
- Update your Origami Build Service urls to use the Origami Build Service v3 API instead of v2.
- Run your project locally and confirm it is still working correctly.
Your migration to npm Origami components is finished! 🎉
Using Origami via Bower
- Run the project locally in its current state.
- 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.
- 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.
- Now you’re ready to do the NPM migration.
- If the project is not using NPM version 7:
- Clean the directory of
node_modulesand any built artefacts - Switch to NPM version 7 and install the dependencies
- Confirm the project is still working correctly - If it is not working, try deleting the
package-lock.jsonand/ornpm-shrinkwrap.jsonfiles and runnpm installagain. There is a known issue with upgrading to NPM version 7 and those files becoming corrupted.
- Clean the directory of
- Clean the directory of
node_modulesand any built artefacts - Install all origami dependencies as npm dependencies and remove them from the
bower.jsonfile. All the components are under the@financialt-timesnamespace on NPM. I.E. To install o-table,npm install @financial-times/o-table. - If there are still dependencies declared in the
bower.jsonfile, try and find the corresponding package on the NPM registry. - Remove the
bower.jsonfile and.bowerrcfile if it exists. E.G.rm -f .bowerrc bower.json - Remove the
bower_componentsdirectory.rm -rf bower_components - Remove
bowerfrom thepackage.jsonfile. E.G.npm uninstall bower - Update the Sass compiler’s
includePathconfiguration to includenode_modulesand removebower_components. - Update the Origami Sass imports to include the
@financial-timesnamespace. E.G.@import 'o-icons/main';becomes@import '@financial-times/o-icons/main';- Note: Although we don’t recommend it, you may also add
node_modules/@financial-timesto your compiler’sincludePathconfiguration. This will resolve Sass published under@financial-timeswithout 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.
- Note: Although we don’t recommend it, you may also add
- Update your Origami JavaScript imports to include the
@financial-timesnamespace. E.G.import oTracking from 'o-tracking';becomesimport oTracking from '@financial-times/o-tracking';andimport 'o-layout';becomesimport '@financial-times/o-layout'; - 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.
- Run your project locally in its current state and confirm it is still working correctly
- 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.
- If your project is not using NPM version 7:
- Clean the directory of node_modules and any built artefacts
- Switch to NPM version 7 and install the dependencies
- Confirm your project is still working correctly - If it is not working, try deleting the
package-lock.jsonand/ornpm-shrinkwrap.jsonfiles and runnpm installagain. There is a known issue with upgrading to NPM version 7 and those files becoming corrupted.
- Confirm your project is still working correctly - If it is not working, try deleting the
- Clean the directory of node_modules and any built artefacts
- Upgrade to the latest major versions of any Origami components you are using
- If using
lockspotoris-origami-flat, these should be removed as they are no longer needed when using NPM version 7.npm uninstall lockspot is-origami-flat - 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:
| 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: