From bf6d0315b2ddb0445cf82e426575d04bb58c4cd6 Mon Sep 17 00:00:00 2001 From: shannonbux <32467162+shannonbux@users.noreply.github.com> Date: Tue, 9 Jan 2018 17:42:26 -0700 Subject: [PATCH] Some major changes (#3388) * Some major changes I streamlined this to just one option: CSS Modules. I saved all the text that I took out in case we need it later or want to put it back in. One edit that I wrote in my notebook, which I now don't understand, reads: "Tell people to create `src/pages/about-styled-components.js` * Update index.md * Reintroducing Glamor and Styled Components as "bonus" items Now they are separate mini-tutorials. * Update index.md * Update index.md --- docs/tutorial/part-two/index.md | 273 ++++---------------------------- 1 file changed, 33 insertions(+), 240 deletions(-) diff --git a/docs/tutorial/part-two/index.md b/docs/tutorial/part-two/index.md index 8debd930c00da..d41e3d4ce7d6e 100644 --- a/docs/tutorial/part-two/index.md +++ b/docs/tutorial/part-two/index.md @@ -108,8 +108,9 @@ plugins. ## Installing your first Gatsby plugin -Let's start by creating a new site. Similar to Part One, run the following to -create a new site. +Let's start by creating a new site. At this point it probably makes sense to close the terminal window(s) you used to build tutorial-part-one so that you don't accidentally start building tutorial-part-two in the wrong place. If you don't close tutorial-part-one prior to building tutorial-part-two, you will see that tutorial-part-two appears at localhost:8001 instead of localhost:8000. + +Similar to part one, open a new terminal window and run the following to create a new site: gatsby new tutorial-part-two https://github.com/gatsbyjs/gatsby-starter-hello-world @@ -124,8 +125,8 @@ This creates a new site with the following structure. This is the minimal setup for a Gatsby site. -To install a plugin, there's two steps. First you install the plugin's NPM -package and second you add the plugin to your site's `gatsby-config.js`. +To install a plugin, there are two steps. First, you install the plugin's NPM +package and second, you add the plugin to your site's `gatsby-config.js`. Typography.js has a Gatsby plugin, so let's install that by running: @@ -133,8 +134,8 @@ Typography.js has a Gatsby plugin, so let's install that by running: npm install --save gatsby-plugin-typography ``` -Next, create a file at the root of your project folder named `gatsby-config.js`. -This is where you add plugins to a site along with other site configuration. +Next, in your code editor, create a file at the root of your project folder named `gatsby-config.js`. +This is where you add plugins along with other site configuration. Copy the following into `gatsby-config.js` @@ -146,7 +147,7 @@ module.exports = { Gatsby reads the site's config file when starting. Here we tell it to look for a plugin named `gatsby-plugin-typography`. Gatsby knows to look for plugins that -are NPM packages so it will find the package we installed previously. +are NPM packages, so it will find the package we installed previously. Now run `gatsby develop`. Once you load the site, if you inspect the generated HTML using the Chrome developer tools, you'll see that the typography plugin @@ -195,7 +196,7 @@ in the middle of the page. To create this, add the following styles to the `
` in `src/pages/index.js`. ```jsx{4} -import React from "react" +import React from "react"; export default () =>
@@ -229,8 +230,8 @@ Ah, this is starting to look nice! What we're seeing here is the default CSS Typography.js produces. We can easily customize it, however. Let's do that. -In your site, create a new directory at `src/utils`. There create a file named -`typography.js`. In it, add the following code. +In your site, create a new directory at `src/utils`. In that directory, create a file named +`typography.js`. In that file, add the following code. ```javascript import Typography from "typography"; @@ -256,17 +257,16 @@ module.exports = { } ``` -Stop `gatsby develop` and then restart it again for our plugin change to take -effect. +Stop `gatsby develop` by typing Ctrl + c into the terminal window where the development process has been running. Then, run `gatsby develop` again to restart it. This will allow our plugin change to take effect. -Now all the text font sizes should be slightly bigger. Try changing the +Now, all the text font sizes should be slightly bigger. Try changing the `baseFontSize` to `24px` then `12px`. All elements get resized as their `font-size` is based on the `baseFontSize`. There are [many themes available](https://github.com/KyleAMathews/typography.js#published-typographyjs-themes) -for Typography.js. Let's try a couple. Run in your terminal at the root of your -site: +for Typography.js. Let's try a couple. In your terminal at the root of your +site, run: ```shell npm install --save typography-theme-bootstrap typography-theme-lawton @@ -275,8 +275,8 @@ npm install --save typography-theme-bootstrap typography-theme-lawton To use the Bootstrap theme, change your typography code to: ```javascript{2,4} -import Typography from "typography" -import bootstrapTheme from "typography-theme-bootstrap" +import Typography from "typography"; +import bootstrapTheme from "typography-theme-bootstrap"; const typography = new Typography(bootstrapTheme) @@ -290,9 +290,9 @@ Bootstrap theme does this. Replace your typography module code with the following, then restart the dev server (necessary to load the new Google Fonts). ```javascript{2-3,5} -import Typography from "typography" +import Typography from "typography"; // import bootstrapTheme from "typography-theme-bootstrap" -import lawtonTheme from "typography-theme-lawton" +import lawtonTheme from "typography-theme-lawton"; const typography = new Typography(lawtonTheme) @@ -307,32 +307,20 @@ Typography.js has more than 30 themes! ## Component CSS -Gatsby has a wealth of options available for styling components. Let's explore -three very popular and production-ready options. We'll build the same page three -times to explore each styling option. - -Each is a variant on "CSS-in-JS"—which solves many of the problems with -traditional CSS. +Gatsby has a wealth of options available for styling components. In this tutorial, we'll explore +one very popular method: CSS Modules. -One of the most important problems they solve is selector name collisions. With -traditional CSS, you have to be careful not to overwrite CSS selectors used -elsewhere in a site because all CSS selectors live in the same global namespace. -This unfortunate restriction can lead to elaborate (and often confusing) -selector naming schemes. +### CSS-in-JS -With CSS-in-JS, you avoid all that as CSS selectors are scoped automatically to -their component. Styles are tightly coupled with their components. This makes it -very easy to know how to edit a component's CSS as there's never any confusion -about how and where CSS is being used. +While we won't cover CSS-in-JS in this initial tutorial, we encourage you to explore CSS-in-JS libraries as these solve many of the problems with traditional CSS plus help make your React components even smarter. There are mini-tutorials for two libraries, [Glamor](/docs/glamor.md) and [Styled Components](/docs/styled-components.md). Check out the following resources for background reading on CSS-in-JS: -For some background reading on CSS-in-JS, see [Christopher "vjeux" Chedeau's 2014 presentation that sparked this movement](https://speakerdeck.com/vjeux/react-css-in-js) as well as [Mark Dalgleish's more recent post "A Unified Styling Language"](https://medium.com/seek-blog/a-unified-styling-language-d0c208de2660). ### CSS Modules -Let's explore first **CSS Modules**. +Let's explore **CSS Modules**. Quoting from [the CSS Module homepage](https://github.com/css-modules/css-modules): @@ -340,7 +328,7 @@ Quoting from > A **CSS Module** is a CSS file in which all class names and animation names > are scoped locally by default. -CSS Modules is very popular, as it lets you write CSS like normal but with a lot +CSS Modules is very popular as it lets you write CSS like normal but with a lot more safety. The tool automatically makes class and animation names unique so you don't have to worry about selector name collisions. @@ -354,7 +342,7 @@ Let's build a page using CSS Modules. First, let's create a new `Container` component which we'll use for each of the CSS-in-JS examples. Create a `components` directory at `src/components` and then, in this directory, create a file named `container.js` and paste the -following. +following: ```javascript import React from "react"; @@ -394,6 +382,8 @@ First, let's create the file for the CSS at with `.module.css` instead of `.css` like normal. This is how we tell Gatsby that this CSS file should be processed as CSS modules. +Paste the following into the file: + ```css .user { display: flex; @@ -436,7 +426,7 @@ import styles from "./about-css-modules.module.css"; console.log(styles); ``` -If you open the developer console in your browser you'll see: +If you open the developer console (using e.g. Firefox or Chrome's developer tools) in your browser, you'll see: ![css-modules-console](css-modules-console.png) @@ -450,17 +440,17 @@ where some CSS is being used. Let's use our styles to create a `User` component. Let's create the new component inline in the `about-css-modules.js` page -component. The general rule of thumb is if you use a component in multiple +component. The general rule of thumb is this: if you use a component in multiple places on a site, it should be in its own module file in the `components` directory. But, if it's used only in one file, create it inline. Modify `about-css-modules.js` so it looks like the following: ```jsx{6-17,23-30} -import React from "react" -import styles from "./about-css-modules.module.css" +import React from "react"; +import styles from "./about-css-modules.module.css"; -import Container from "../components/container" +import Container from "../components/container"; const User = props =>
@@ -496,204 +486,7 @@ The finished page should now look like: ![css-modules-final](css-modules-final.png) -### Glamor - -Let's create the same page using -[Glamor](https://github.com/threepointone/glamor). - -Glamor lets you write _real_ CSS inline in your components using the same Object -CSS syntax React supports for the `style` prop. - -First install the Gatsby plugin for Glamor. - -```shell -npm install --save gatsby-plugin-glamor -``` - -And then add it to your `gatsby-config.js` - -```javascript{9} -module.exports = { - plugins: [ - { - resolve: `gatsby-plugin-typography`, - options: { - pathToConfigModule: `src/utils/typography.js`, - }, - }, - `gatsby-plugin-glamor`, - ], -} -``` - -Restart `gatsby develop` again to enable the Glamor plugin. - -Now create the Glamor page at `src/pages/about-glamor.js` - -```jsx -import React from "react"; -import Container from "../components/container"; - -export default () => ( - -

About Glamor

-

Glamor is cool

- -); -``` - -Let's add the same inline `User` component but this time using Glamor's `css` -prop. - -```jsx{5-27,33-40} -import React from "react" - -import Container from "../components/container" - -const User = props => -
- -
-

- {props.username} -

-

- {props.excerpt} -

-
-
- -export default () => - -

About Glamor

-

Glamor is cool

- - - -``` - -The final Glamor page should look identical to the CSS Modules page. - -![glamor-example](glamor-example.png) - -### Styled Components - -For our final CSS-in-JS example, we'll try -[Styled Components](https://www.styled-components.com/). - -Styled Components lets you use actual CSS syntax inside your components. - -First, like normal, we'll install the Gatsby plugin for Styled Components. - -```sh -npm install --save gatsby-plugin-styled-components styled-components -``` - -Then modify the `gatsby-config.js`. Before we can use Styled Components however, -we'll need to remove the Glamor plugin and delete the Glamor component page we -created. The two plugins conflict with each other as both want to take control -during server rendering. - -```javascript{9} -module.exports = { - plugins: [ - { - resolve: `gatsby-plugin-typography`, - options: { - pathToConfigModule: `src/utils/typography.js`, - }, - }, - `gatsby-plugin-styled-components`, - ], -} -``` - -Then at `src/pages/about-styled-components.js` create: - -```jsx -import React from "react"; -import styled from "styled-components"; - -import Container from "../components/container"; - -const UserWrapper = styled.div` - display: flex; - align-items: center; - margin: 0 auto 12px auto; - &:last-child { - margin-bottom: 0; - } -`; - -const Avatar = styled.img` - flex: 0 0 96px; - width: 96px; - height: 96px; - margin: 0; -`; - -const Description = styled.div` - flex: 1; - margin-left: 18px; - padding: 12px; -`; - -const Username = styled.h2` - margin: 0 0 12px 0; - padding: 0; -`; - -const Excerpt = styled.p` - margin: 0; -`; - -const User = props => ( - - - - {props.username} - {props.excerpt} - - -); - -export default () => ( - -

About Styled Components

-

Styled Components is cool

- - - -); -``` ### Other CSS options