chore(recipe):Creating a new site using a theme #20595
Conversation
| @@ -4,6 +4,72 @@ title: "Recipes: Working with Themes" | |||
|
|
|||
| A [Gatsby theme](/docs/themes/what-are-gatsby-themes) abstracts Gatsby configuration (shared functionality, data sourcing, design) into an installable package. This means that the configuration and functionality isn’t directly written into your project, but rather versioned, centrally managed, and installed as a dependency. You can seamlessly update a theme, compose themes together, and even swap out one compatible theme for another. | |||
|
|
|||
| ## Creating a new site using a theme | |||
|
|
|||
| Found a theme you'd like to use on your project? Awesome! You can work through setting up by following the steps below. | |||
There was a problem hiding this comment.
| Found a theme you'd like to use on your project? Awesome! You can work through setting up by following the steps below. | |
| Found a theme you'd like to use on your project? Awesome! You can configure it for use by following the steps below. |
|
|
||
| Found a theme you'd like to use on your project? Awesome! You can work through setting up by following the steps below. | ||
|
|
||
| > If you'd like to take a look at more theme options, you could take a look at this [list of themes](https://www.npmjs.com/search?q=gatsby-theme) . |
There was a problem hiding this comment.
| > If you'd like to take a look at more theme options, you could take a look at this [list of themes](https://www.npmjs.com/search?q=gatsby-theme) . | |
| > If you'd like to take a look at more theme options, check out this [list of themes](https://www.npmjs.com/search?q=gatsby-theme). |
|
|
||
| ### Prerequisities | ||
|
|
||
| The [Gatsby CLI](/docs/gatsby-cli) installed |
There was a problem hiding this comment.
| The [Gatsby CLI](/docs/gatsby-cli) installed | |
| Make sure you have the [Gatsby CLI](/docs/gatsby-cli) installed. |
| gatsby new {your-project-name} | ||
| ``` | ||
|
|
||
| 2. Change directory and install theme |
There was a problem hiding this comment.
| 2. Change directory and install theme | |
| 2. Change directory and install theme | |
| In this example, our theme is `gatsby-theme-blog`. You can replace that reference with whatever your theme is named. |
Thoughts on doing it this way instead of having the additional example snippet?
|
|
||
| ```shell | ||
| cd {your-project-name} | ||
| npm install {theme-name} |
There was a problem hiding this comment.
| npm install {theme-name} | |
| npm install gatsby-theme-blog |
| npm install {theme-name} | ||
| ``` | ||
|
|
||
| For Example |
There was a problem hiding this comment.
If we take the above recommendation then this whole section is uneeded
|
|
||
| ``` | ||
|
|
||
| 3. Add theme to `gatsby.config.js` |
There was a problem hiding this comment.
| 3. Add theme to `gatsby.config.js` | |
| 3. Add theme to `gatsby.config.js` | |
| Follow the instructions found in the README of the theme you're using to determine what configuration it requires. |
| } | ||
| ``` | ||
|
|
||
| 4. Run `yarn develop` , the theme should be avaliable at `http://localhost:8000/{basePath}` |
There was a problem hiding this comment.
Based on this we likely need to include yarn installation as a pre-req as well? Or can they run gatsby develop instead?
There was a problem hiding this comment.
I'll add yarn to the pre-req. It's used mostly with themes because of Yarn workspaces.
There was a problem hiding this comment.
For sure, my question is whether workspaces are necessary for using themes? Or just developing them? The theme starter example uses gatsby develop so figured it was worth double-checking. I don't actually know the answer, so if you're up to test it out that'd be awesome.
There was a problem hiding this comment.
I don't think workspaces are necessary for using themes. Also, I saw that running yarn develop triggers gatsby develop.
There was a problem hiding this comment.
So let's try using just gatsby develop and if it's successful you can open a new PR making the change and removing the yarn dependency :)
There was a problem hiding this comment.
Hey so I checked and gatsby develop works and I will send in a PR for that . Although I would want to add a note for using yarn install . seems gatsby new keeps the yarn.lock and deleting the package-lock.json file which is then leading to the weird behaviour with running npm install. Can we agree to have this as a note?
There was a problem hiding this comment.
Hmm, I'd love to understand this a bit better. You're saying that when you create a new gatsby project it's creating a yarn.lock file? That shouldn't be the case as gatsby new uses npm. Would love to see what steps you took and where the yarn.lock came into play! I'm not inclined to include any notes about yarn if you don't need to use it in this scenario. I'm wondering if the issues you're seeing are because you already had?
There was a problem hiding this comment.
if someone uses before gatsby in combination with yarn, then yarn is used instead of npm.
Ekwuno
added
bot: merge on green
Description
Using a Theme" recipe requires you to use a starter. For people wanting to know how to install and use a theme, starters create extra cognitive overhead: "what if I want to install a theme that isn't part of a starter? This PR adds a section for "Creating a new site using a theme"
Documentation
https://www.gatsbyjs.org/docs/recipes/working-with-themes
Related Issues
Related to #20114