|
| 1 | +<!-- shared header START --> |
| 2 | + |
| 3 | +<p align="center"> |
| 4 | + <a href="https://www.contentful.com/developers/docs/references/content-management-api/"> |
| 5 | + <img alt="Contentful Logo" title="Contentful" src="images/contentful-icon.png" width="150"> |
| 6 | + </a> |
| 7 | +</p> |
| 8 | + |
| 9 | +<h1 align='center'>Content Management API</h1> |
| 10 | + |
| 11 | +<h3 align="center">Migration</h3> |
| 12 | + |
| 13 | +<p align="center"> |
| 14 | + <a href="README.md">Readme</a> · |
| 15 | + <a href="MIGRATION.md">Migration</a> · · |
| 16 | + <a href="CONTRIBUTING.md">Contributing</a> |
| 17 | +</p> |
| 18 | + |
| 19 | +<p align="center"> |
| 20 | + <a href="https://www.contentful.com/slack/"> |
| 21 | + <img src="https://img.shields.io/badge/-Join%20Community%20Slack-2AB27B.svg?logo=slack&maxAge=31557600" alt="Join Contentful Community Slack"> |
| 22 | + </a> |
| 23 | +</p> |
| 24 | + |
| 25 | +<!-- shared header END --> |
| 26 | + |
| 27 | +# Migration information |
| 28 | + |
| 29 | +- [Migration information](#migration-information) |
| 30 | + - [Migration to version 12.x](#migration-to-version-12x) |
| 31 | + - [Breaking changes](#breaking-changes) |
| 32 | + - [Node.js core modules](#nodejs-core-modules) |
| 33 | + - [Pre-bundled code](#pre-bundled-code) |
| 34 | + - [Webpack 5](#webpack-5) |
| 35 | + - [Rollup](#rollup) |
| 36 | + - [Improvements](#improvements) |
| 37 | + - [Tree shaking](#tree-shaking) |
| 38 | + - [Module support and package configuration](#module-support-and-package-configuration) |
| 39 | + - [Testing framework](#testing-framework) |
| 40 | + - [Security](#security) |
| 41 | + - [Removal of eval](#removal-of-eval) |
| 42 | + |
| 43 | +From version 3.0.0 onwards, you can access documentation for a specific version by visiting `https://contentful.github.io/contentful-management.js/contentful-management/<VERSION>`. |
| 44 | + |
| 45 | +You can upgrade to a major version using `npm update contentful` |
| 46 | + |
| 47 | +## Migration to version 12.x |
| 48 | + |
| 49 | +Version 12.0.0 introduces full ESM support by default, with CJS variants still available for legacy environments. This version is a significant step forward in modernizing our build and improving performance while maintaining wide compatibility across various environments. |
| 50 | + |
| 51 | +### Breaking changes |
| 52 | + |
| 53 | +#### Node.js core modules |
| 54 | + |
| 55 | +We no longer bundle Node.js core modules. If you’re bundling for the browser, you may need to configure your bundler to provide fallbacks or empty functions, particularly for the fs module. This change was introduced in version 12.x and may affect projects using Node.js-specific modules in the browser. |
| 56 | + |
| 57 | +#### Pre-bundled code |
| 58 | + |
| 59 | +Pre-bundled code for Node.js is no longer provided. If your setup relies on pre-bundled packages, you may need to adjust your build configuration. |
| 60 | + |
| 61 | +##### Webpack 5 |
| 62 | + |
| 63 | +To make our project bundle properly for the browser with Webpack 5, you need to add this to your configuration: |
| 64 | + |
| 65 | +```js |
| 66 | +module.exports = { |
| 67 | + resolve: { |
| 68 | + fallback: { |
| 69 | + os: false, |
| 70 | + zlib: false, |
| 71 | + tty: false, |
| 72 | + }, |
| 73 | + }, |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +##### Rollup |
| 78 | + |
| 79 | +To make our project bundle properly for the browser with Rollup, you need to add this to your configuration: |
| 80 | + |
| 81 | +```js |
| 82 | +nodeResolve({ browser: true, preferBuiltins: false }) |
| 83 | +``` |
| 84 | + |
| 85 | +### Improvements |
| 86 | + |
| 87 | +#### Tree shaking |
| 88 | + |
| 89 | +Tree shaking is significantly improved, ensuring that only the necessary parts of the library are included in your final bundle. |
| 90 | +Smaller browser bundles |
| 91 | + |
| 92 | +Browser bundle sizes have been reduced by nearly threefold, from 128KB to 45KB, contributing to faster load times and improved performance. |
| 93 | + |
| 94 | +#### Module support and package configuration |
| 95 | + |
| 96 | +The package now uses "type": "module" in package.json to define the default module format as ESM, while also providing support for CJS through the exports field. This allows us to support a wide range of environments including Node.js (with and without TypeScript, both CJS and ESM), AngularJS, GatsbyJS, Next.js, Nuxt, React Native (Expo), Rollup, Svelte, Vite, Webpack, and more. |
| 97 | + |
| 98 | +#### Testing framework |
| 99 | + |
| 100 | +We’ve migrated our internal test environment from Jest to Vitest, aligning with modern testing frameworks and tools. |
| 101 | + |
| 102 | +## Security |
| 103 | + |
| 104 | +### Removal of eval |
| 105 | + |
| 106 | +We have completely removed the use of eval in our exported code, improving security and compatibility with strict environments. |
0 commit comments