Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): Update building-a-theme to latest Theme UI #32357

Merged
merged 3 commits into from
Jul 14, 2021
Merged

chore(docs): Update building-a-theme to latest Theme UI #32357

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ecf8573
Update building-a-theme.md
ezeYaniv Jul 13, 2021
20e2559
more copy edits
LekoArts Jul 14, 2021
9df9464
chore: format
Jul 14, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 34 additions & 67 deletions docs/tutorial/building-a-theme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
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