README.md

Checkout

Table of Contents

• Pre-requisites
• Checkout SDK Quick Start Guide
• Widgets Library Quick Start Guide
  • Widgets Development Locally
• Project structure

Pre-requisites

Install dependencies for the workspace

yarn install

Checkout SDK Quick Start Guide

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.

Running in dev mode using the immutable-devnet network:

yarn start:dev

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:

yarn start

Running the Checkout SDK Sample App with the Checkout SDK supporting hot reloading:

# Run the Checkout SDK first
# Context: checkout-sdk in ./sdk
yarn start

# Run the Checkout SDK Sample App in a new terminal
# Context: checkout-sdk-sample-app in ./sdk-sample-app
yarn start

Building to the ./sdk/dist directory for dev environment:

yarn build:dev

Building to the ./sdk/dist directory for sandbox/production environment:

yarn build

Running all jest tests:

yarn test

Running changed tests on save in watch mode:

yarn test:watch

Linting:

yarn lint

Linting and attempting to auto-fix issues:

yarn lint:fix

Typechecking:

yarn typecheck

Generate Typescript API documentation (viewable in the newly generated docs folder at ./sdk/docs/README.md):

yarn docs

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.

Running in dev mode (widgets-lib depends upon checkout-sdk):

# 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

Running the Widgets Sample App with the Widgets Library supporting hot reloading:

# Run the above two commands first
# ...

# Run the Widgets Sample App in a new terminal
# Context: checkout-widgets-sample-app in ./widgets-sample-app
yarn start

Read more about running locally here.

Building the Widgets Library to the ./widgets-lib/dist directory:

yarn build

Building the Widgets Library and outputting a bundle visualizer:

yarn build:analyze

Running all jest tests:

yarn test

Running changed jest tests on save in watch mode:

yarn test:watch

Linting:

yarn lint

Linting and attempting to auto-fix issues:

yarn lint:fix

Typechecking:

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

# Run the Checkout SDK first in local dev mode
# Context: checkout-sdk in ./sdk
yarn start:local

# Build the Widgets Library in a new terminal in local mode
# Context: checkout-widgets in ./widgets-lib
yarn build:local

# 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

Project structure

─ checkout
      │
      ├── sdk - Checkout SDK
      │
      ├── sdk-sample-app - Sample app where the Checkout SDK is consumed
      │
      ├── widgets-lib - Commerce Widgets
      │
      ├── widgets-sample-app - Sample app where the Commerce Widgets are consumed
      │
      └── README.md

Read more about the Checkout SDK here