Skip to content

Commit

Permalink
chore(docs): Update building-a-theme to latest Theme UI (#32357)
Browse files Browse the repository at this point in the history 
Co-authored-by: Lennart <lekoarts@gmail.com>
Co-authored-by: gatsbybot <mathews.kyle+gatsbybot@gmail.com>
  • Loading branch information
@ezeYaniv @LekoArts
3 people committed Jul 14, 2021
1 parent 97df178 commit d576cc2
Showing 1 changed file with 34 additions and 67 deletions.
101 changes: 34 additions & 67 deletions docs/tutorial/building-a-theme.md
View file
Expand Up @@ -6,7 +6,7 @@ In this tutorial, you'll learn how to build a theme plugin for Gatsby. This tuto

## Set up yarn workspaces

In this section, you'll learn how to structure folders and configure Yarn workspaces to develop Gatsby themes. You'll create two workspaces, `gatsby-theme-events` and `site`.
In this section, you'll learn how to structure folders and configure yarn workspaces to develop Gatsby themes. You'll create two workspaces, `gatsby-theme-events` and `site`.

Each workspace can be run separately, as well as one depending on the other. In this example, `gatsby-theme-events` will be a dependency of `site`.

Expand Down Expand Up @@ -105,7 +105,7 @@ You should now see the following dependencies in your `site/package.json`:
```json:title=site/package.json
{
"dependencies": {
"gatsby": "^2.9.11",
"gatsby": "^3.0.0",
"gatsby-theme-events": "*",
"react": "^17.0.0",
"react-dom": "^17.0.0"
Expand Down Expand Up @@ -140,29 +140,16 @@ Targeting the `gatsby-theme-events` workspace, install `gatsby`, `react`, and `r
yarn workspace gatsby-theme-events add -P gatsby react react-dom
```

### Add development dependencies to `gatsby-theme-events`

During development, you'll use your theme as a regular Gatsby site, so you'll also set `gatsby`, `react`, and `react-dom` as dev dependencies:

```shell
yarn workspace gatsby-theme-events add -D gatsby react react-dom
```

> 💡 The `-P` flag is shorthand for installing peer dependencies, and the `-D` flag is shorthand for installing dev dependencies.
> 💡 The `-P` flag is shorthand for installing peer dependencies.
The `gatsby-theme-events/package.json` file should now include the following:

```json:title=gatsby-theme-events/package.json
{
"peerDependencies": {
"gatsby": "^3.0.0",
"react": "^16.9.0 || ^17.0.0",
"react-dom": "^16.9.0 || ^17.0.0"
},
"devDependencies": {
"gatsby": "^3.0.0",
"react": "^16.9.0",
"react-dom": "^16.9.0"
"react": "^17.0.0",
"react-dom": "^17.0.0"
}
}
```
Expand Down Expand Up @@ -313,7 +300,7 @@ exports.onPreBootstrap = ({ reporter }) => {

// highlight-start
// Define the "Event" type
exports.sourceNodes = ({ actions }) => {
exports.createSchemaCustomization = ({ actions }) => {
actions.createTypes(`
type Event implements Node @dontInfer {
id: ID!
Expand Down Expand Up @@ -353,7 +340,7 @@ exports.onPreBootstrap = ({ reporter }) => {
}

// Define the "Event" type
exports.sourceNodes = ({ actions }) => {
exports.createSchemaCustomization = ({ actions }) => {
actions.createTypes(`
type Event implements Node @dontInfer {
id: ID!
Expand Down Expand Up @@ -1026,7 +1013,7 @@ exports.onPreBootstrap = ({ reporter }, options) => {
// {...}
}

exports.sourceNodes = ({ actions }) => {
exports.createSchemaCustomization = ({ actions }) => {
// {...}
}

Expand Down Expand Up @@ -1098,7 +1085,7 @@ You can make your theme styles extendable using the `gatsby-plugin-theme-ui` pac
Install dependencies:

```shell
yarn workspace gatsby-theme-events add gatsby-plugin-theme-ui theme-ui @emotion/react @emotion/styled @mdx-js/react
yarn workspace gatsby-theme-events add gatsby-plugin-theme-ui theme-ui
```

Then, add the `gatsby-plugin-theme-ui` plugin to the `gatsby-theme-events/gatsby-config.js` file:
Expand Down Expand Up @@ -1267,24 +1254,24 @@ yarn workspace site develop

![Theme UI changes starting to take effect on the site. For example, the header is now purple.](./images/building-a-theme-theme-ui-changes.png)

To continue applying theme styles, you can use the `Styled` import from Theme UI. For example, in the `event-list.js` component, change the `<h1>`, `<ul>` and `<li>` elements to reference their themed styles:
To continue applying theme styles, you can use the [`Themed` import](https://theme-ui.com/themed) from Theme UI. For example, in the `event-list.js` component, change the `<h1>`, `<ul>` and `<li>` elements to reference their themed styles:

```jsx:title=gatsby-theme-events/src/components/event-list.js
import React from "react"
import { Link } from "gatsby"
// highlight-next-line
import { Styled } from "theme-ui"
import { Themed } from "theme-ui"

const EventList = ({ events }) => {
return (
<>
// highlight-next-line
<Styled.h1>Upcoming Events</Styled.h1>
<Themed.h1>Upcoming Events</Themed.h1>
// highlight-next-line
<Styled.ul>
<Themed.ul>
{events.map(event => (
// highlight-next-line
<Styled.li key={event.id}>
<Themed.li key={event.id}>
<strong>
<Link to={event.slug}>{event.name}</Link>
</strong>
Expand All @@ -1296,18 +1283,18 @@ const EventList = ({ events }) => {
})}{" "}
in {event.location}
// highlight-next-line
</Styled.li>
</Themed.li>
))}
// highlight-next-line
</Styled.ul>
</Themed.ul>
</>
)
}

export default EventList
```

By replacing the `h1` with `Styled.h1`, `ul` with `Styled.ul`, and `li` with `Styled.li`, the theme styles for those elements have been applied:
By replacing the `h1` with `Themed.h1`, `ul` with `Themed.ul`, and `li` with `Themed.li`, the theme styles for those elements have been applied:

![Theme UI style changes showing on the events listing.](./images/building-a-theme-events-listing-styling.png)

Expand All @@ -1334,23 +1321,15 @@ It's important to namespace your theme. It helps differentiate between published
"develop": "gatsby develop"
},
"peerDependencies": {
"gatsby": "^2.13.19",
"react": "^16.9.0 || ^17.0.0",
"react-dom": "^16.9.0 || ^17.0.0"
},
"devDependencies": {
"gatsby": "^2.13.19",
"react": "^16.9.0",
"react-dom": "^16.9.0"
"gatsby": "^3.0.0",
"react": "^17.0.0",
"react-dom": "^17.0.0"
},
"dependencies": {
"@emotion/react": "^11.0.0",
"@emotion/styled": "^11.0.0",
"@mdx-js/react": "^1.0.27",
"gatsby-plugin-theme-ui": "^0.2.6",
"gatsby-source-filesystem": "^2.1.5",
"gatsby-transformer-yaml": "^2.2.2",
"theme-ui": "^0.2.13"
"gatsby-plugin-theme-ui": "^0.10.0",
"gatsby-source-filesystem": "^3.0.0",
"gatsby-transformer-yaml": "^3.0.0",
"theme-ui": "^0.10.0"
}
}
```
Expand Down Expand Up @@ -1388,7 +1367,7 @@ npm publish --access public

> 💡 Because it's namespaced, you'll need to include public access.
Now it's published! After publishing, you'll be able to find your theme on npm at npmjs.com/{yourpackagename}
Now it's published! After publishing, you'll be able to find your theme on npm at `npmjs.com/{yourpackagename}`

## Consume a theme in a Gatsby application

Expand All @@ -1401,8 +1380,8 @@ Make a new directory called `theme-test`, and set up the project:
```shell
mkdir theme-test
cd theme-test
yarn init -y
yarn add react react-dom gatsby @jlengstorf/gatsby-theme-events
npm init -y
npm install react react-dom gatsby @jlengstorf/gatsby-theme-events
```

> 💡 Where it says `@jlengstorf/gatsby-theme-events`, use the theme you just published instead! Or if you didn't want to actually publish your test theme, go ahead and use `@jlengstorf/gatsby-theme-events`.
Expand All @@ -1419,17 +1398,9 @@ module.exports = {
}
```

### Install the Gatsby CLI

Run:

```shell
yarn global add gatsby-cli
```

### Run the site

Making sure you're in your `/theme-test` directory, run `gatsby develop` to start the site.
Making sure you're in your `/theme-test` directory, run `npm run develop` to start the site.

![The new site, running your new Gatsby theme.](./images/building-a-theme-running-theme.png)

Expand Down Expand Up @@ -1471,26 +1442,22 @@ Your file tree will look like this:
├── .gitignore
├── gatsby-config.js
├── package.json
└── yarn.lock
└── package-lock.json
```

Inside the new `index.js` file, add the following:

```javascript:title=theme-test/src/gatsby-plugin-theme-ui/index.js
import merge from "lodash.merge"
import { merge } from "theme-ui"
import { theme } from "@jlengstorf/gatsby-theme-events"

export default merge({}, theme, {
const theme = merge(theme, {
colors: {
primary: "blue",
},
})
```

You'll be using `lodash.merge`, so install that now:

```shell
yarn add lodash.merge
export default theme
```

Restart the dev server for `theme-test`. Your local site should now have a blue header instead of a purple one:
Expand All @@ -1500,7 +1467,7 @@ Restart the dev server for `theme-test`. Your local site should now have a blue
A few notable things are happening in this `index.js` file:

- The `theme` import from `@jlengstorf/gatsby-theme-events` is the base UI theme from `@jlengstorf/gatsby-theme-events`.
- The new object exported from `index.js` uses `lodash.merge` to deeply merge the base UI theme with the theme overrides of your choice. In this case, changing the primary color to blue.
- The new object exported from `index.js` uses [`merge` from Theme UI](https://theme-ui.com/guides/merging-themes) to deeply merge the base UI theme with the theme overrides of your choice. In this case, changing the primary color to blue.

### Override an entire component

Expand All @@ -1520,7 +1487,7 @@ Inside `src`, create a folder with the same title as your theme.
├── .gitignore
├── gatsby-config.js
├── package.json
└── yarn.lock
└── package-lock.lock
```

Anything inside `theme-test/src/@jlengstorf/gatsby-theme-events` will "shadow" the components in `@jlengstorf/gatsby-theme-events`.
Expand Down

0 comments on commit d576cc2

Please sign in to comment.