You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+72-17Lines changed: 72 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,51 +10,104 @@ Currently we link to the latest build of [Primer CSS] so that we may use current
10
10
11
11
## Installation
12
12
13
-
Install primer-react in your project with npm:
13
+
Install @primer/components in your project with npm:
14
14
15
15
```
16
-
npm install primer-react
16
+
npm install @primer/components
17
17
```
18
18
19
19
## Usage
20
20
21
21
**If you are upgrading from a version before `1.0.0-beta`, please read the [migration docs](migrating.md).**
22
22
23
-
All of our components are exported by name from `primer-react`, so you can import them with:
23
+
All of our components are exported by name from `@primer/components`, so you can import them with:
24
24
25
25
```js
26
26
import {
27
27
Box,
28
28
Button,
29
29
Heading,
30
30
Text
31
-
} from'primer-react'
31
+
} from'@primer/components'
32
32
```
33
33
34
34
### Styling
35
35
36
-
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.
36
+
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.
37
37
38
-
To ensure proper styling, you'll need to link to the most recent build of [Primer CSS] in one of the following ways:
38
+
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`.
39
39
40
-
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:
40
+
#### JavaScript bundlers
41
+
If you're using a JavaScript bundler that supports CSS imports, you can import it in your bundles directly:
41
42
42
-
```js
43
-
{
44
-
test:/\.css$/,
45
-
use: ['style-loader', 'css-loader']
46
-
}
47
-
```
43
+
```js
44
+
import'@primer/components/dist/css/build.css'
45
+
```
46
+
47
+
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.
48
+
49
+
```js
50
+
{
51
+
module: {
52
+
rules: [
53
+
{
54
+
test:/\.css$/,
55
+
use:'style-loader'
56
+
}
57
+
]
58
+
}
59
+
}
60
+
```
61
+
62
+
#### Server inlining
63
+
If you run a Node server, you can read the file from disk at startup:
Then, inline it into the `<head>` of your HTML template(s) or render it server-side in React like so:
72
+
73
+
```jsx
74
+
// assuming the `css` variable is set as above
75
+
exportdefault () => (
76
+
<html>
77
+
<head>
78
+
<style>{css}</style>
79
+
</head>
80
+
<body>
81
+
...
82
+
</body>
83
+
</html>
84
+
)
85
+
```
86
+
87
+
#### Static apps
88
+
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`:
1.**For pre-production applications**, you can link directly to [the build on unpkg.com](https://unpkg.com/primer/build/build.css).
102
+
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.
50
103
51
-
1. Otherwise, you can `npm install --save primer` and either or link `node_modules/primer/build/build.css`to your source directory.
104
+
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].
52
105
53
106
## Local Development
54
107
55
-
To run `primer-react` locally when adding or updating components:
108
+
To run `@primer/components` locally when adding or updating components:
56
109
57
-
1. Clone this repo:`git clone https://github.com/primer/primer-react`
110
+
1. Clone this repo: `git clone https://github.com/primer/components`
58
111
1. Install dependencies: `npm install`
59
112
1. Run the dev app: `npm run dev`
60
113
@@ -73,3 +126,5 @@ To run `primer-react` locally when adding or updating components:
73
126
74
127
[emotion]: https://emotion.sh/
75
128
[Primer CSS]: https://github.com/primer/primer
129
+
[flash of unstyled content]: https://en.wikipedia.org/wiki/Flash_of_unstyled_content
@@ -170,6 +171,16 @@ In this case, you will need to deal explicitly with two props passed down from [
170
171
*`className`: You _must_ render this prop, otherwise **your component will not be styled.**
171
172
*`is`: This is what allows your component to render with arbitrary elements, and even other components. If you don't respect this prop, you should `delete Component.propTypes.is` to signal that it's not available.
172
173
174
+
## Writing documentation
175
+
176
+
We use [Next.js](https://github.com/zeit/next.js/) and [MDX Docs](https://github.com/jxnblk/mdx-docs/) to power our documentation site at [https://primer.style/components](https://primer.style/components/).
177
+
178
+
To add a new component to our documentation site:
179
+
180
+
1. Create a new file with the `.md` extension for your component in `pages/components/docs`.
181
+
2. Copy & paste the template from `doc-template.md` & replace placeholder brackets with relevant information.
182
+
3. Add the new file to the `index.js` in `pages/components/docs`
183
+
173
184
## Deployment
174
185
We deploy the Primer Components site using [Now]. Install the Now CLI and log in with:
175
186
@@ -184,10 +195,10 @@ Once you're logged in, sync your local git repo with the `master` branch and run
184
195
script/deploy
185
196
```
186
197
187
-
This will create a new deployment and alias it to its production URL, [primer-react.now.sh](https://primer-react.now.sh).
198
+
This will create a new deployment and alias it to its production URL, [primer-components.now.sh](https://primer-components.now.sh).
188
199
189
200
### Path aliasing
190
-
This site is served as a subdirectory of [primer.style] using a [path alias](https://zeit.co/docs/features/path-aliases) configured in that repo's [`rules.json`](https://github.com/primer/primer.style/tree/master/rules.json). If you change the production deployment URL for this app, you will also need to change it there and re-deploy that app; otherwise, Now will automatically route requests from [primer.style/components](https://primer.style/components/) to the new deployment whenever you deploy this one to `primer-react.now.sh`.
201
+
This site is served as a subdirectory of [primer.style] using a [path alias](https://zeit.co/docs/features/path-aliases) configured in that repo's [`rules.json`](https://github.com/primer/primer.style/tree/master/rules.json). If you change the production deployment URL for this app, you will also need to change it there and re-deploy that app; otherwise, Now will automatically route requests from [primer.style/components](https://primer.style/components/) to the new deployment whenever you alias this one to `primer-components.now.sh`.
0 commit comments