Shopify / post-purchase-ui

MIT License
9 stars 10 forks source link

@shopify/post-purchase-ui-react

This library provides reference implementations of the UI components available in post-purchase checkout extensions. These components are copied from a private Shopify repo periodically to serve primarily as a reference implementation.

This library is intended to be used to help produce WYSIWYG editors for Shopify post-purchase extensions that will use Post-purchase UI Extensions at runtime. Since post-purchase UI Extensions components do not actually render to the DOM, these components help demonstrate the necessary styles and event handling for the UI components that Post-purchase UI Extensions maps to. These are the exact same components used at Shopify to render a Post-purchase UI extension.

More components are available in this package than are provided by Post-purchase UI Extensions. The set of components we provide will grow over time (and if you see anything in this library you would love to add, please raise an issue in the UI Extensions repo), but this library includes all of the UI components we use throughout post-purchase as a convenience for us at Shopify in generating this package. Any components, properties, or other functionality that you see in this package that does not match the component APIs provided by Post-purchase UI Extensions is considered unstable, and may be removed or changed at any time without notice. Additionally, components in this library have no documentation; refer to the Post-purchase UI Extensions component documentation for details on the usage of the many components and props provided by this library.

Installation

@shopify/post-purchase-ui-react is provided as npm package.

yarn add @shopify/post-purchase-ui-react
#or
npm install @shopify/post-purchase-ui-react

Technical details

This library is authored with React. However, the Post-purchase UI Extensions host that Shopify provides aliases all React APIs to Preact, a lightweight alternative to React. If you are using these components directly, we recommend you do the same (see the webpack section below for details).

The UI components in this library require a few pieces of React context, and some global styles. To make this easier for you, we’ve included a single Context component you can wrap around your React application that will provide all of these global requirements. You can import this component from @shopify/post-purchase-ui-react/ui-extensions:

import React from 'react';
import {Context} from '@shopify/post-purchase-ui-react/ui-extensions';
import {Text} from '@shopify/post-purchase-ui-react';

export default function App() {
  return (
    <Context>
      <AppUi />
    </Context>
  );
}

function AppUi() {
  return <Text>I can safely use UI components now!</Text>;
}

webpack

Shopify uses webpack to bundle code for running in the browser. This package provides a function you can use to augment an existing webpack configuration with all that is necessary to properly build this library. This includes additional configuration for handling the JavaScript build outputs for this library, as well as CSS, SVGs, and other assets.

// in webpack.config.js

const {addWebpackConfig} = require('@shopify/post-purchase-ui-react/webpack');

module.exports = addWebpackConfig({
  // Your own webpack config goes here
});

// `addWebpackConfig` accepts some options to customize the build
module.exports = addWebpackConfig(
  {
    // Your own webpack config goes here
  },
  {
    // disable the automatic `preact` aliasing:
    preact: false,
    // whether build is for development or production. Defaults to `NODE_ENV === "development"`
    development: true,
  },
);

If you are not using webpack to bundle your application, you will need to replicate the handling of various file types in the build tool you are using. Additionally, unlike with Shopify’s Polaris component library, this library does not offer plain HTML/ CSS assets.

Contributing

As noted above, this repo is periodically updated from a private Shopify repo that is the source of truth. As a result, no contributions are currently being accepted for this library.

License

MIT © Shopify, see LICENSE.md for details.

Shopify