6.0.38 • Published 25 days ago

@shipengine/alchemy v6.0.38

Weekly downloads
-
License
-
Repository
-
Last release
25 days 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

3 months ago

6.0.26

3 months ago

6.0.25

4 months ago

6.0.24

4 months ago

6.0.29

2 months ago

6.0.28

3 months ago

6.0.23

4 months ago

6.0.22

5 months ago

6.0.21

5 months ago

6.0.20

6 months ago

6.0.16

8 months ago

6.0.15

8 months ago

6.0.14

8 months ago

6.0.19

6 months ago

6.0.18

7 months ago

6.0.17

7 months ago

6.0.38

25 days ago

6.0.37

27 days ago

6.0.36

1 month ago

6.0.35

1 month ago

6.0.30

2 months ago

6.0.34

1 month ago

6.0.33

1 month ago

6.0.32

1 month ago

6.0.31

1 month ago

6.0.13

8 months ago

6.0.12

9 months ago

6.0.11

9 months ago

6.0.10

9 months ago

6.0.7

10 months ago

6.0.6

10 months ago

6.0.9

10 months ago

6.0.8

10 months ago

5.4.25

11 months ago

5.4.26

11 months ago

5.4.23

11 months ago

5.4.24

11 months ago

5.4.21

11 months ago

5.4.22

11 months ago

5.4.20

11 months ago

6.0.1

11 months ago

6.0.0

11 months ago

6.0.3

10 months ago

6.0.2

11 months ago

6.0.5

10 months ago

6.0.4

10 months ago

5.4.18

12 months ago

5.4.19

11 months ago

5.4.16

12 months ago

5.4.17

12 months ago

5.4.14

12 months ago

5.4.15

12 months 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

1 year ago

5.1.10

1 year ago

5.1.9

1 year ago

5.1.8

1 year ago

5.1.7

1 year ago

5.1.6

1 year ago

5.1.5

1 year ago

5.1.4

1 year ago

5.1.3

1 year ago

5.1.2

1 year ago

5.1.1

1 year ago

5.0.30

1 year ago

5.0.29

1 year ago

5.1.0

1 year ago

5.0.28

1 year ago

5.0.26

1 year ago

5.0.27

1 year ago

5.0.23

1 year ago

5.0.24

1 year ago

5.0.25

1 year ago

5.0.22

1 year ago

5.0.21

1 year ago

5.0.20

1 year ago

5.0.18

1 year ago

5.0.19

1 year ago

5.0.17

1 year ago

5.0.16

1 year ago

5.0.15

1 year ago

5.0.13

1 year ago

5.0.14

1 year ago

5.0.9

1 year ago

5.0.8

1 year ago

5.0.7

1 year ago

5.0.10

1 year ago

5.0.11

1 year ago

5.0.12

1 year ago

5.0.6

1 year ago

5.0.5

1 year ago

5.0.4

1 year ago

5.0.3

1 year ago

5.0.2

1 year ago

5.0.1

1 year ago

5.0.0

1 year ago

4.2.3

1 year 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

2 years ago

0.4.10

2 years ago

0.4.9

2 years ago

0.4.8

2 years ago

0.4.7

2 years ago

0.4.6

2 years ago

0.4.5

2 years ago

0.4.4

2 years ago

0.4.3

2 years ago

0.4.2

2 years ago

0.4.1

2 years ago

0.4.0

2 years ago

0.3.7

2 years ago

0.3.6

2 years ago

0.3.5

2 years ago

0.3.4

2 years ago

0.3.3

2 years ago

0.3.2

2 years ago

0.3.1

2 years ago

0.3.0

2 years ago

0.2.0

2 years ago

0.1.3

2 years ago

1.0.0-next.2

2 years ago

1.0.0-next.1

2 years ago

0.1.2-next.0

2 years ago

0.1.2

2 years ago

0.1.1

2 years ago

0.1.0

2 years ago