Merge pull request #260 from primer/base-css

Add back Primer CSS build and instructions for using it
primer · Sep 20, 2018 · 315a501 · 315a501
2 parents 59a4ee6 + d6085c9
commit 315a501
Show file tree

Hide file tree

Showing 13 changed files with 2,507 additions and 6,488 deletions.
diff --git a/README.md b/README.md
@@ -33,22 +33,75 @@ import {
 
 ### Styling
 
-This project uses [emotion] under the hood to generate static CSS from _some_ component styles, but still relies on [Primer CSS] for some component styles that haven't yet been ported over.
+This project uses [emotion] to generate static CSS for most component styles, but still relies on [Primer CSS] for some classname-based styles that haven't yet been ported over.
 
-To ensure proper styling, you'll need to link to the most recent build of [Primer CSS] in one of the following ways:
+To ensure proper styling of all Primer components, you'll need to include some static CSS that's distributed with the `@primer/components` npm package in `dist/primer-components.css`.
 
-1. If you're using webpack, you can install [style-loader](https://github.com/webpack-contrib/style-loader) and [css-loader](), `import 'primer/build/build.css'` in your bundle, and include the following in your webpack config's `module.rules` list:
+#### JavaScript bundlers
+If you're using a JavaScript bundler that supports CSS imports, you can import it in your bundles directly:
 
-    ```js
-    {
-      test: /\.css$/,
-      use: ['style-loader', 'css-loader']
-    }
-    ```
+```js
+import '@primer/components/dist/css/build.css'
+```
+
+If you're using webpack, you will need to install [style-loader](https://github.com/webpack-contrib/style-loader) and  configure webpack to use it for imports ending in '.css', e.g.
+
+```js
+{
+  module: {
+    rules: [
+      {
+        test: /\.css$/,
+        use: 'style-loader'
+      }
+    ]
+  }
+}
+```
+
+#### Server inlining
+If you run a Node server, you can read the file from disk at startup:
+
+```jsx
+const {readFileSync} = require('fs')
+const cssPath = require.resolve('@primer/components/dist/primer-components.css')
+const css = readFileSync(cssPath, 'utf8')
+```
+
+Then, inline it into the `<head>` of your HTML template(s) or render it server-side in React like so:
+
+```jsx
+// assuming the `css` variable is set as above
+export default () => (
+  <html>
+    <head>
+      <style>{css}</style>
+    </head>
+    <body>
+      ...
+    </body>
+  </html>
+)
+```
+
+#### Static apps
+For fully static or statically generated (Jekyll, Hugo, etc.) apps, you may need to manually copy `node_modules/@primer/components/dist/css/build.css` (after `npm install --save @primer/components`) to one of your site's public directories, i.e. `/assets`:
+
+```sh
+cp node_modules/@primer/components/dist/css/build.css assets/primer-components.css
+```
+
+Then link to it in the `<head>` of your HTML document(s):
+
+```html
+<link rel="stylesheet" href="/assets/primer-components.css">
+```
+
+### Static CSS rendering
 
-1. **For pre-production applications**, you can link directly to [the build on unpkg.com](https://unpkg.com/primer/build/build.css).
+Some Primer components rendered client-side may produce a [flash of unstyled content]. You can avoid most jarring flashes by ensuring that `primer-components.css` is either inlined or linked in the `<head>` of your document with one of the techniques described above.
 
-1. Otherwise, you can `npm install --save primer` and either or link `node_modules/primer/build/build.css` to your source directory.
+If you're rendering React components both server-side _and_ client-side, we suggest following [Emotion's server-side rendering instructions](https://emotion.sh/docs/ssr) to avoid the flash of unstyled content for server-rendered components. This repo's [documentation template component](https://github.com/primer/components/blob/master/pages/_document.js) demonstrates how to do this in [Next.js].
 
 ## Local Development
 
@@ -73,3 +126,5 @@ To run `@primer/components` locally when adding or updating components:
 
 [emotion]: https://emotion.sh/
 [Primer CSS]: https://github.com/primer/primer
+[flash of unstyled content]: https://en.wikipedia.org/wiki/Flash_of_unstyled_content
+[Next.js]: https://github.com/zeit/next.js
diff --git a/next.config.js b/next.config.js
@@ -1,8 +1,9 @@
 const withPlugins = require('next-compose-plugins')
-const sass = require('@zeit/next-sass')
-const mdx = require('@zeit/next-mdx')({extension: /\.mdx?$/})
+const mdx = require('@zeit/next-mdx')
 
-module.exports = withPlugins([sass, mdx], {
+module.exports = withPlugins([
+  mdx({extension: /\.mdx?$/})
+], {
   /*
    * Note: Prefixing assets with the fully qualified deployment URL
    * makes them available even when the site is served from a path alias, as in
@@ -15,6 +16,12 @@ module.exports = withPlugins([sass, mdx], {
   },
 
   webpack(config, {dev}) {
+    // load primer-components.css as raw string
+    config.module.rules.push({
+      test: /\.css$/,
+      use: 'raw-loader'
+    })
+
     // we only care about disabling mangling in production
     if (dev) {
       return config