Docs: [DX-2907] Update README of "checkout" package (#1880)

immutable · Jun 11, 2024 · 325cb7e · 325cb7e
1 parent 88c064c
commit 325cb7e
Showing 1 changed file with 149 additions and 103 deletions.
diff --git a/packages/checkout/README.md b/packages/checkout/README.md
@@ -1,178 +1,224 @@
-<div align="center">
-  <p align="center">
-    <a href="https://docs.x.immutable.com/docs">
-      <img src="https://cdn.dribbble.com/users/1299339/screenshots/7133657/media/837237d447d36581ebd59ec36d30daea.gif" width="280"/>
-    </a>
-  </p>
-  <h1>Immutable Checkout SDK</h1>
-</div>
+# Checkout
 
-# Overview
+## Table of Contents
 
-> **Warning** **IMMUTABLE CHECKOUT SDK IS UNSTABLE** <br/>
-> Since it has not hit the version 1.0 yet, its public interface should not be considered final. Future releases may include breaking changes without further notice. We will do our best to keep this documentation updated providing visibility on breaking changes planned.
+- [Pre-requisites](#pre-requisites)
+- [Checkout SDK Quick Start Guide](#checkout-sdk-quick-start-guide)
+- [Widgets Library Quick Start Guide](#widgets-library-quick-start-guide)
+  - [Widgets Development Locally](#widgets-development-locally)
+- [Project structure](#project-structure)
 
-The Immutable Checkout SDK provides both programatical and user interfaces for interacting with various wallets and L2 networks. It provides all the tools to enable transaction ready gamers including on ramping, dex swaps, bridging and more.
+### Pre-requisites
 
-## Documentation
+Install dependencies for the workspace
 
-- Coming Soon &trade;
-
-# Project structure
-
-```
-/
-│
-└───sdk -> Checkout SDK
-│
-└───sdk-sample-app --> Sample app where the Checkout SDK is consumed
-│
-└───widgets-lib --> Checkout widgets
-│
-└───widgets-sample-app --> Sample app where the Checkout Widgets are consumed
-│
-└───README.md
+```bash
+yarn install
 ```
 
-# Running locally
+### Checkout SDK Quick Start Guide
 
-## Dependencies
+All commands below need to be run in the context of the `checkout-sdk` package in the `./sdk` folder unless specified otherwise. Read more about context [here](../../../README.md#context).
 
-CheckoutSDK has been built with and tested using the following dependencies.
+Running in `dev` mode using the `immutable-devnet` network:
 
-| Dependency | Version |
-| ---------- | ------- |
-| Node       | v16+    |
-| Yarn       | v3.5.0  |
+```bash
+yarn start:dev
+```
 
-Node Module dependencies are still added to the package.json of each checkout module, however each module installs it's dependencies to a shared node_modules directory at the root level of the Unified SDK. This requires dependency versions to be aligned across all SDK submodules.
+Running in `sandbox`/`production` mode using the `immutable-testnet`/`mainnet` network based on the environment value set for the `SANDBOX_CONFIGURATION` config object in the `./sdk/src/sdk.ts` file:
 
-Once you've added a new dependency, or if it's your first time, go to the root level of the Unified SDK and run `yarn install`.
+```bash
+yarn start
+```
 
-## Checkout SDK Development
+Running the Checkout SDK Sample App with the Checkout SDK supporting hot reloading:
+
+```bash
+# Run the Checkout SDK first
+# Context: checkout-sdk in ./sdk
+yarn start
 
-Running Checkout SDK in different modes:
+# Run the Checkout SDK Sample App in a new terminal
+# Context: checkout-sdk-sample-app in ./sdk-sample-app
+yarn start
+```
 
-For local/development mode (uses immutable-devnet):
+Building to the `./sdk/dist` directory for `dev` environment:
 
+```bash
+yarn build:dev
 ```
-cd sdk
-yarn start:dev
+
+Building to the `./sdk/dist` directory for `sandbox`/`production` environment:
+
+```bash
+yarn build
 ```
 
-For sandbox/production mode (uses immutable-testnet/mainnet based on config object):
+Running all jest tests:
 
+```bash
+yarn test
 ```
-cd sdk
-yarn start
+
+Running changed tests on save in watch mode:
+
+```bash
+yarn test:watch
 ```
 
-To run the SDK Sample App with the Checkout SDK hot reloading, you need to run both the Checkout SDK and the Checkout Sample App at the same time.
+Linting:
 
-In one terminal run;
+```bash
+yarn lint
+```
+
+Linting and attempting to auto-fix issues:
 
+```bash
+yarn lint:fix
 ```
-cd sdk
-yarn start
+
+Typechecking:
+
+```bash
+yarn typecheck
 ```
 
-In another terminal run;
+Generate Typescript API documentation (viewable in the newly generated docs folder at [./sdk/docs/README.md](./sdk/docs/README.md)):
 
+```bash
+yarn docs
 ```
-cd sdk-sample-app
+
+### Widgets Library Quick Start Guide
+
+All commands below need to be run in the context of the `checkout-widgets` package in the `./widgets-lib` folder unless specified otherwise. Read more about context [here](../../../README.md#context).
+
+Running in `dev` mode (widgets-lib depends upon checkout-sdk):
+
+```bash
+# Run the Checkout SDK first
+# Context: checkout-sdk in ./sdk
+yarn start:dev
+
+# Run the Widgets Library in a new terminal
+# Context: checkout-widgets in ./widgets-lib
 yarn start
 ```
 
-Note: SDK sample app does not require mode settings.
+Running the Widgets Sample App with the Widgets Library supporting hot reloading:
 
-Now when you make changes in the SDK, Rollup will trigger a rebuild of the SDK and since the sample app is also being watched and one of it's dependencies has changed, it will also recompile and the change will automatically be pulled through.
+```bash
+# Run the above two commands first
+# ...
 
-The best way to work on the SDK is to run the sample app and the sdk, then create buttons for the endpoint you're developing and use them to trigger SDK calls.
+# Run the Widgets Sample App in a new terminal
+# Context: checkout-widgets-sample-app in ./widgets-sample-app
+yarn start
+```
 
-### Jest tests in the SDK
+**Read more about running locally [here](#widgets-development-locally).**
 
-All jest tests within the SDK are run in the jsdom environment. To configure this so that it works in our CI pipeline, please add the following comment to the top of your test file.
+Building the Widgets Library to the `./widgets-lib/dist` directory:
 
+```bash
+yarn build
 ```
-/*
- * @jest-environment jsdom
- */
+
+Building the Widgets Library and outputting a bundle visualizer:
+
+```bash
+yarn build:analyze
 ```
 
-## Widgets Development
+Running all jest tests:
+
+```bash
+yarn test
+```
 
-The widgets-sample-app depends upon the widgets-lib, which in turn depends upon the sdk. To get started you will need to run `yarn start` in all three directories. This will enable hot reloading for all areas.
+Running changed jest tests on save in watch mode:
 
+```bash
+yarn test:watch
 ```
-cd sdk
-yarn start
+
+Running cypress tests headless:
+
+```bash
+yarn test:cypress
 ```
 
+Running cypress tests:
+
+```bash
+yarn test:cypress:open
 ```
-cd widgets-lib
-yarn start
+
+Linting:
+
+```bash
+yarn lint
 ```
 
+Linting and attempting to auto-fix issues:
+
+```bash
+yarn lint:fix
 ```
-cd widgets-sample-app
-yarn start
+
+Typechecking:
+
+```bash
+yarn typecheck
 ```
 
+#### Widgets Development Locally
+
 When you develop locally, the widgets-sample-app installs and imports the widgets as an es module. `import { WidgetsFactory} from '@imtbl/checkout-widgets'` This helps local development with hot reloading. (it takes a lot longer to rebuild and minify a browser bundle).
 
 In production however, the widgets-lib package is built as a browser bundle and is dynamically included in the DOM when you call `await checkout.widgets()`.
 
 To test this setup locally and force the widgets bundle to be loaded from `localhost` you will need to run
 
-```
-cd sdk
+```bash
+# Run the Checkout SDK first in local dev mode
+# Context: checkout-sdk in ./sdk
 yarn start:local
 ```
 
-```
-cd widgets-lib
+```bash
+# Build the Widgets Library in a new terminal in local mode
+# Context: checkout-widgets in ./widgets-lib
 yarn build:local
 ```
 
-```
-cd widgets-sample-app
+```bash
+# Run the Widgets Sample App in a new terminal
+# Context: checkout-widgets-sample-app in ./widgets-sample-app
 yarn start
 ```
 
 You will then need to make sure that you replace your creation of a `new WidgetsFactory()` with a call to `await checkout.widgets()` within the sample app. This will pull in the built widgets.js bundle dynamically, but from your local filesystem.
 
 In a production release, this script is loaded from a CDN. We are currently using `https://cdn.jsdelivr.net/npm/@imtbl/sdk/dist/browser/checkout/widgets.js`
 
-# Linting
-
-Linting gets run across the project when you try to commit to your banch and it wont let you push unless the linting passes.
-
-# Running tests
-
-Running jest tests
+### Project structure
 
 ```
-yarn test
+─ checkout
+      │
+      ├── sdk - Checkout SDK
+      │
+      ├── sdk-sample-app - Sample app where the Checkout SDK is consumed
+      │
+      ├── widgets-lib - Checkout widgets
+      │
+      ├── widgets-sample-app - Sample app where the Checkout Widgets are consumed
+      │
+      └── README.md
 ```
 
-Running cypress tests
-
-```
-yarn test:cypress:open
-```
-
-Running cypress tests (headless)
-
-```
-yarn test:cypress
-```
-
-# Release process
-
-## Staging
-
-- Coming Soon &trade;
-
-## Production
-
-- Coming Soon &trade;
+[Read more about the Checkout SDK here](../../README.md#checkout)