npm package: @hover/gatsby-plugin
Description: Drop-in Blueprint support for Gatsby sites
Author: Syed Mohsin
Latest version: 4.0.0

<div align="center">
  <br>
  <a href="https://www.gatsbyjs.com/"><img height="100" src="https://user-images.githubusercontent.com/288160/140416582-6a0b6620-d3c7-4d5e-bee0-f1716fba0f44.png" alt="Gatsby Logo"></a>
  <br>
  <h1>Blueprint Gatsby Plugin</h1>
  <p>Turn-key solution for using <strong>Blueprint</strong> in a <a href="https://www.gatsbyjs.com/">Gatsby</a> site</a></p>
</div>

## Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Installation

To use Blueprint in your Gatsby site, you need to install the plugin and its
peer dependencies.

```sh
npm i @hover/gatsby-plugin @hover/blueprint @emotion/react @emotion/styled framer-motion

# or

yarn add @hover/gatsby-plugin @hover/blueprint @emotion/react @emotion/styled framer-motion
```

## Usage

1. Add `@hover/gatsby-plugin` as a plugin in your Gatsby config.

```js
// gatsby-config.js
module.exports = {
  plugins: ["@hover/gatsby-plugin"],
}
```

2. Use Blueprint

```jsx
// src/pages/index.js
import React from "react"
import { Box, Body } from "@hover/blueprint"

function IndexPage() {
  return (
    <Box padding={600}>
      <Body size={500}>Hello World</Text>
    </Box>
  )
}

export default IndexPage
```

## Plugin options

By default, this plugin adds the main context provider (`BlueprintProvider`) to make all components work correctly. Any `options` specified in the plugin configuration will be passed to the `BlueprintProvider`.

- **BlueprintProvider** composes **ChakraProvider**, which configures the Blueprint theme and accepts [ChakraProvider Props](https://chakra-ui.com/docs/getting-started#chakraprovider-props)

```jsx
<BlueprintProvider resetCSS={resetCSS} portalZIndex={portalZIndex}>
  {element}
</BlueprintProvider>
```

You can disable either of these with Gatsby options:

```js
// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "@hover/gatsby-plugin",
      options: {
        /**
         * @property {boolean} [resetCSS=false]
         * if `false`, this plugin will not use `<CSSReset />
         */
        resetCSS: true,
        /**
         * @property {number} [portalZIndex=40]
         * The z-index to apply to all portal nodes. This is useful
         * if your app uses a lot z-index to position elements.
         */
        portalZIndex: 40,
      },
    },
  ],
}
```

## Customizing the theme

> ⚠️ Note: this should only be necessary for augmenting or adding components that Blueprint does not support. Any necessary customizations should be discussed with the design systems team so we can consider incorporating them upstream in [**@hover/chakra-theme**](/packages/chakra-theme).

To use customize the theme in your Gatsby site, you can shadow the plugin's
`src/@hover/gatsby-plugin/theme.js` file with your own theme:

```js
// src/@hover/gatsby-plugin/theme.js
import { extendTheme } from "@hover/blueprint"

const theme = {
  colors: {
    primary: "rebeccapurple",
  },
}

export default extendTheme(theme)
```

You can learn more about custom theme at
[Chakra UI's documentation](https://chakra-ui.com/theme).