6.0.38 • Published 4 months ago

@shipengine/alchemy v6.0.38

Weekly downloads
-
License
-
Repository
-
Last release
4 months ago

Alchemy

shipengine/alchemy is a toolkit for building re-usable, fully-featured, data-connected and cross-compatible React components (“Elements”)^1 for use in applications that utilize the ShipEngine API.

The library makes opinionated choices about API access, state management, language translations^2 and UI foundations.

Features:

  • Available to all descendants of the AlchemyProvider:

    • A batteries-included client for accessing ShipeEngine API endpoints with a shared cache and lifecycle management via hooks from @shipengine/react-api.
    • A ShipEngine Giger theme, which can be re-defined at instantiation via the themeConfig prop and accessible on the Emotion css callback prop, and icons via Giger's Icon component.
  • Available to components created via the alchemy.createElement factory:

    • Fully isolated styles. CSS styles are reset at the boundary of each Element, ensuring that they are self-contained and unaffected by the host application’s styles.
    • Fully isolated language translations. A non-global instance of i18next is provided for each Element. Individual translations can be overriden at the Element's point-of-use via the optional resources prop.
    • A configurable ErrorBoundary.

Basic Usage

!IMPORTANT In addition to @shipengine/alchemy, you must also add @shipengine/react-api and @shipengine/js-api to your project's dependencies.

  • A single AlchemyProvider should be rendered near the top of the application's component hiearchy
  • The createElement factory is used to create stylistically isolated components that will utilize the AlchemyProvider's API client and theme.
import alchemy, { AlchemyProvider, useListShipments } from "@shipengine/alchemy";
import { themeConfig } from "../themeConfig";

type MyComponentProps = {
  myProp: string;
};

const MyComponent = ({ myProp }: MyComponentProps) => {
  const { data, isLoading, error } = useListShipments();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>{error.message}</div>;

  console.log(data);
  // > an object matching the response schema of https://shipengine.github.io/shipengine-openapi/#operation/list_shipments

  return (
    <div
      css={(theme) => ({
        /* ... */
      })}
    >
      Retrieved {data.shipments.length} shipments
    </div>
  );
};

// Your own component that the ErrorBoundary will display when an error occurs
const MyErrorFallback = ({ error }) => <div>Whoops...</div>;

const MyElement = alchemy.createElement(
  MyComponent,
  MyErrorFallback,
  // optional configuration object
  {
    // applied to the container
    css: (theme) => ({
      // ...
    }),

    // i18next translations
    resources: {
      // ...
    },
  }
);

const MyApp = () => {
  return (
    <AlchemyProvider getToken={() => "your-platform-token"} themeConfig={themeConfig}>
      <section>
        Your pre-existing application
        <div>
          Locate the Element wherever you like
          <MyElement
            myProp="just a regular prop"
            // optional translations override prop added by the factory
            resources={{}}
          />
        </div>
      </section>
    </AlchemyProvider>
  );
};
6.0.27

6 months ago

6.0.26

6 months ago

6.0.25

6 months ago

6.0.24

7 months ago

6.0.29

5 months ago

6.0.28

5 months ago

6.0.23

7 months ago

6.0.22

7 months ago

6.0.21

8 months ago

6.0.20

8 months ago

6.0.16

10 months ago

6.0.15

10 months ago

6.0.14

11 months ago

6.0.19

9 months ago

6.0.18

9 months ago

6.0.17

10 months ago

6.0.38

4 months ago

6.0.37

4 months ago

6.0.36

4 months ago

6.0.35

4 months ago

6.0.30

5 months ago

6.0.34

4 months ago

6.0.33

4 months ago

6.0.32

4 months ago

6.0.31

4 months ago

6.0.13

11 months ago

6.0.12

12 months ago

6.0.11

12 months ago

6.0.10

1 year ago

6.0.7

1 year ago

6.0.6

1 year ago

6.0.9

1 year ago

6.0.8

1 year ago

5.4.25

1 year ago

5.4.26

1 year ago

5.4.23

1 year ago

5.4.24

1 year ago

5.4.21

1 year ago

5.4.22

1 year ago

5.4.20

1 year ago

6.0.1

1 year ago

6.0.0

1 year ago

6.0.3

1 year ago

6.0.2

1 year ago

6.0.5

1 year ago

6.0.4

1 year ago

5.4.18

1 year ago

5.4.19

1 year ago

5.4.16

1 year ago

5.4.17

1 year ago

5.4.14

1 year ago

5.4.15

1 year ago

5.4.12

1 year ago

5.4.13

1 year ago

5.4.10

1 year ago

5.4.11

1 year ago

5.4.9

1 year ago

5.4.8

1 year ago

5.4.7

1 year ago

5.4.6

1 year ago

5.4.5

1 year ago

5.4.4

1 year ago

5.4.3

1 year ago

5.4.2

1 year ago

5.4.1

1 year ago

5.4.0

1 year ago

5.3.1

1 year ago

5.3.0

1 year ago

5.2.0

1 year ago

5.1.18

1 year ago

5.1.17

1 year ago

5.1.16

1 year ago

5.1.15

1 year ago

5.1.14

1 year ago

5.1.13

1 year ago

5.1.12

1 year ago

5.1.11

2 years ago

5.1.10

2 years ago

5.1.9

2 years ago

5.1.8

2 years ago

5.1.7

2 years ago

5.1.6

2 years ago

5.1.5

2 years ago

5.1.4

2 years ago

5.1.3

2 years ago

5.1.2

2 years ago

5.1.1

2 years ago

5.0.30

2 years ago

5.0.29

2 years ago

5.1.0

2 years ago

5.0.28

2 years ago

5.0.26

2 years ago

5.0.27

2 years ago

5.0.23

2 years ago

5.0.24

2 years ago

5.0.25

2 years ago

5.0.22

2 years ago

5.0.21

2 years ago

5.0.20

2 years ago

5.0.18

2 years ago

5.0.19

2 years ago

5.0.17

2 years ago

5.0.16

2 years ago

5.0.15

2 years ago

5.0.13

2 years ago

5.0.14

2 years ago

5.0.9

2 years ago

5.0.8

2 years ago

5.0.7

2 years ago

5.0.10

2 years ago

5.0.11

2 years ago

5.0.12

2 years ago

5.0.6

2 years ago

5.0.5

2 years ago

5.0.4

2 years ago

5.0.3

2 years ago

5.0.2

2 years ago

5.0.1

2 years ago

5.0.0

2 years ago

4.2.3

2 years ago

4.2.2

2 years ago

4.2.1

2 years ago

4.1.8

2 years ago

4.1.7

2 years ago

4.0.1

2 years ago

4.0.0

2 years ago

3.0.3

2 years ago

3.0.2

2 years ago

3.0.1

2 years ago

3.0.0

2 years ago

4.1.4

2 years ago

4.1.3

2 years ago

4.1.6

2 years ago

4.1.5

2 years ago

4.1.0

2 years ago

4.1.2

2 years ago

4.1.1

2 years ago

2.4.1

2 years ago

2.4.0

2 years ago

2.3.4

2 years ago

2.3.3

2 years ago

2.3.2

2 years ago

2.3.1

2 years ago

2.3.0

2 years ago

2.2.4

2 years ago

2.2.3

2 years ago

2.2.2

2 years ago

2.2.1

2 years ago

2.2.0

2 years ago

2.1.9

2 years ago

2.1.8

2 years ago

2.1.7

2 years ago

2.1.6

2 years ago

2.1.5

2 years ago

2.1.3

2 years ago

2.1.2

2 years ago

2.1.1

2 years ago

2.1.0

2 years ago

2.0.1

2 years ago

2.0.0

2 years ago

1.0.5

2 years ago

1.0.4

2 years ago

1.0.3

2 years ago

1.0.2

2 years ago

1.0.1

2 years ago

1.0.0

2 years ago

0.5.16

2 years ago

0.5.15

2 years ago

0.5.14

2 years ago

0.5.13

2 years ago

0.5.12

2 years ago

0.5.11

2 years ago

0.5.10

2 years ago

0.5.9

2 years ago

0.5.8

2 years ago

0.5.7

2 years ago

0.5.6

2 years ago

0.5.5

2 years ago

0.5.4

2 years ago

0.5.3

2 years ago

0.5.2

2 years ago

0.5.1

2 years ago

0.5.0

2 years ago

0.4.24

2 years ago

0.4.23

2 years ago

0.4.22

2 years ago

0.4.21

2 years ago

0.4.20

2 years ago

0.4.19

2 years ago

0.4.18

2 years ago

0.4.17

2 years ago

0.4.16

2 years ago

0.4.15

2 years ago

0.4.14

2 years ago

0.4.13

2 years ago

0.4.12

2 years ago

0.4.11

3 years ago

0.4.10

3 years ago

0.4.9

3 years ago

0.4.8

3 years ago

0.4.7

3 years ago

0.4.6

3 years ago

0.4.5

3 years ago

0.4.4

3 years ago

0.4.3

3 years ago

0.4.2

3 years ago

0.4.1

3 years ago

0.4.0

3 years ago

0.3.7

3 years ago

0.3.6

3 years ago

0.3.5

3 years ago

0.3.4

3 years ago

0.3.3

3 years ago

0.3.2

3 years ago

0.3.1

3 years ago

0.3.0

3 years ago

0.2.0

3 years ago

0.1.3

3 years ago

1.0.0-next.2

3 years ago

1.0.0-next.1

3 years ago

0.1.2-next.0

3 years ago

0.1.2

3 years ago

0.1.1

3 years ago

0.1.0

3 years ago