@shipengine/alchemy v6.0.38
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 Emotioncss
callback prop, and icons via Giger'sIcon
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 optionalresources
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>
);
};
3 months ago
3 months ago
4 months ago
4 months ago
2 months ago
3 months ago
4 months ago
5 months ago
5 months ago
6 months ago
8 months ago
8 months ago
8 months ago
6 months ago
7 months ago
7 months ago
25 days ago
27 days ago
1 month ago
1 month ago
2 months ago
1 month ago
1 month ago
1 month ago
1 month ago
8 months ago
9 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
10 months ago
11 months ago
10 months ago
10 months ago
12 months ago
11 months ago
12 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago