From e86ebc54e5e6903a6d96813bc02eb48ad5514cce Mon Sep 17 00:00:00 2001 From: Sam Blacklock Date: Mon, 22 Jul 2024 12:54:32 +0100 Subject: [PATCH] feat: add a migration guide (#3) --- MIGRATION_GUIDE.md | 73 +++++++++++++++++++++++++++++++ README.md | 42 ++++++++++-------- examples/express-app/index.js | 2 +- examples/express-app/package.json | 2 +- examples/express-app/yarn.lock | 2 +- 5 files changed, 100 insertions(+), 21 deletions(-) create mode 100644 MIGRATION_GUIDE.md diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md new file mode 100644 index 0000000..4c788dd --- /dev/null +++ b/MIGRATION_GUIDE.md @@ -0,0 +1,73 @@ +# Migration Guide: @moltin/sdk to @elasticpath/js-sdk + +## Background and rationale + +The Elastic Path Commerce Cloud JavaScript SDK has been migrated from `@moltin/sdk` to `@elasticpath/js-sdk`. This was an overdue change, and will allow us to consolidate our version control usage behind the @elasticpath namespace. + +We are also taking this opportunity to entirely remove legacy naming (moltin) from the codebase to avoid confusion. + +## Key Changes + +- **Package Name**: The package name has changed from `@moltin/sdk` to `@elasticpath/js-sdk`. +- **GitHub Repository**: The GitHub repository has moved from `moltin/js-sdk` to `elasticpath/js-sdk`. + +> ![NOTE] +> We are aligning the package name with the repository name, i.e. `js-sdk`, rather than just `sdk`. We are reserving the `sdk` name for future use. + +## Installation + +### Old Package Installation + +```bash +npm install --save @moltin/sdk +``` + +### New Package Installation + +Replace the old package with the new one: + +```bash +npm install --save @elasticpath/js-sdk +``` + +## Example Usage + +### Importing the SDK + +#### Old Usage + +```js +import { gateway as MoltinGateway } from '@moltin/sdk' + +const Moltin = MoltinGateway({ + client_id: 'XXX' +}) +``` + +#### New Usage + + +```js +import { gateway as ElasticPathGateway } from '@elasticpath/js-sdk' + +const ElasticPath = ElasticPathGateway({ + client_id: 'XXX' +}) +``` + +### Migration + +1. **Change the import path**: Update all occurrences of `@moltin/sdk` to `@elasticpath/js-sdk`. +2. **Rename the import alias**: If you are using `MoltinGateway`, change it to `ElasticPathGateway` (or a name of your choice). +3. **Update instance names**: Rename any instances of `Moltin` to `ElasticPath` to maintain consistency and clarity in your codebase. + +If you are directly accessing any of the state the SDK persists in localStorage or cookies, **update your references** like so: + +- **mcart** becomes **epcart** +- **mcurrency** becomes **epcurrency** +- **moltinCredentials** becomes **epCredentials** + +> ![CAUTION] +> Accessing this SDK state directly is **not recommended** + +The compiled SDK and types published in `/dist` as `moltin.cjs.js`, `moltin.d.ts`, `moltin.esm.js`, and `moltin.js` are now published as `index` \ No newline at end of file diff --git a/README.md b/README.md index b4e49ca..cec419a 100644 --- a/README.md +++ b/README.md @@ -2,39 +2,45 @@ # Elastic Path Commerce Cloud JavaScript SDK -[![npm version](https://img.shields.io/npm/v/@elasticpath/sdk.svg)](https://www.npmjs.com/package/@elasticpath/sdk) +[![npm version](https://img.shields.io/npm/v/@elasticpath/js-sdk.svg)](https://www.npmjs.com/package/@elasticpath/js-sdk) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/elasticpath/js-sdk/issues) [![follow on Twitter](https://img.shields.io/twitter/follow/elasticpath?style=social&logo=twitter)](https://twitter.com/intent/follow?screen_name=elasticpath) -> A simple to use API interface to help get you off the ground quickly and efficiently with your Elastic Path Commerce Cloud JavaScript apps. +> [!IMPORTANT] +> This repository has been migrated from [@moltin/sdk](https://www.npmjs.com/package/@moltin/sdk). If you are a previous user of the Moltin SDK, read our [guide](MIGRATION_GUIDE.md) to learn more about migrating your implementation to this codebase + +A simple to use API interface to help get you off the ground quickly and efficiently with your Elastic Path Commerce Cloud JavaScript apps. 📚 [API reference](https://documentation.elasticpath.com/commerce-cloud/docs/developer/get-started/sdk.html#officially-supported-sdk) — 📚 [Elastic Path Commerce Cloud](https://www.elasticpath.com) ## 🛠 Installation -Install the package from [npm](https://www.npmjs.com/package/@elasticpath/sdk) and import in your project. +Install the package from [npm](https://www.npmjs.com/package/@elasticpath/js-sdk) and import in your project. ```bash -npm install --save @elasticpath/sdk +npm install --save @elasticpath/js-sdk ``` ## ⛽️ Usage -To get started, instantiate a new ElasticPath client with your store credentials. +To get started, instantiate a new Elastic Path client with your store credentials. + + +> [!NOTE] +> This requires an [Elastic Path Commerce Cloud](https://www.elasticpath.com) account. You can sign up for a free trial [here](https://cm.elasticpath.com/free-trial) -> **Note:** This requires an [Elastic Path Commerce Cloud](https://www.elasticpath.com) account. ```js // JavaScript -import { gateway as ElasticPathGateway } from '@elasticpath/sdk' +import { gateway as ElasticPathGateway } from '@elasticpath/js-sdk' const ElasticPath = ElasticPathGateway({ client_id: 'XXX' }) // Node.js -const ElasticPathGateway = require('@elasticpath/sdk').gateway +const ElasticPathGateway = require('@elasticpath/js-sdk').gateway const ElasticPath = ElasticPathGateway({ client_id: 'XXX', @@ -45,7 +51,7 @@ const ElasticPath = ElasticPathGateway({ Alternatively you can include the `UMD` bundle via [UNPKG](https://unpkg.com) like so: ``` html - +