Babel plugin #62
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,165 @@ | ||
| import React from 'react'; | ||
| import SectionLayout from '../SectionLayout'; | ||
| import CodeBlock from '../CodeBlock'; | ||
| import Code from '../Code'; | ||
| import Note from '../Note'; | ||
|
|
||
| const installNPM = ` | ||
| npm install --save-dev babel-plugin-styled-components | ||
| `.trim(); | ||
|
|
||
| const usage = ` | ||
| { | ||
| "plugins": ["styled-components"] | ||
| } | ||
| `.trim(); | ||
|
|
||
| const ssr = ` | ||
| { | ||
| "plugins": [ | ||
| ["styled-components", { | ||
| "ssr": true | ||
| }] | ||
| ] | ||
| } | ||
| `.trim(); | ||
|
|
||
| const displayName = ` | ||
| { | ||
| "plugins": [ | ||
| ["styled-components", { | ||
| "displayName": false | ||
| }] | ||
| ] | ||
| } | ||
| `.trim(); | ||
|
|
||
| const preprocess = ` | ||
| { | ||
| "plugins": [ | ||
| ["styled-components", { | ||
| "preprocess": true | ||
| }] | ||
| ] | ||
| } | ||
| `.trim(); | ||
|
|
||
| const minify = ` | ||
| { | ||
| "plugins": [ | ||
| ["styled-components", { | ||
| "minify": false | ||
| }] | ||
| ] | ||
| } | ||
| `.trim(); | ||
|
|
||
| const BabelPlugin = () => | ||
| <SectionLayout title="Babel Plugin" labels={['v2']}> | ||
| <p> | ||
| This plugin adds support for server-side rendering, for minification of | ||
| styles and gives you a nicer debugging experience when using{' '} | ||
| <Code>styled-components</Code>. | ||
| </p> | ||
| <p>Usage</p> | ||
|
There was a problem hiding this comment. This subsection can use the Also, this is missing a small explanation, like:
|
||
| <CodeBlock code={installNPM} language="node" /> | ||
| <p> | ||
| Then in your babel configuration (probably <Code>.babelrc</Code>): | ||
|
There was a problem hiding this comment. This sounds a bit odd. Maybe something like:
would make it nicer |
||
| </p> | ||
| <CodeBlock code={usage} language="node" /> | ||
| <SectionLayout sub title="Server-side rendering"> | ||
| <Note>This option is turned off by default</Note> | ||
| <p> | ||
| By adding a unique identifier to every styled component this plugin | ||
|
There was a problem hiding this comment. Just indicating that we need to replace the mention of "this plugin" with "this option" since each section only talks about a single option :) |
||
| avoids checksum mismatches due to different class generation on the | ||
| client and on the server. If you do not use this plugin and try to | ||
| server-side render <Code>styled-components</Code> React will complain. | ||
|
There was a problem hiding this comment.
This is a bit outdated and also sounds weird, so let's update it:
We also need to add a reference to this babel-plugin option to our SSR section. There was a problem hiding this comment. We also need to add a reference to this babel-plugin option to our SSR section. -> What can I do here ? There was a problem hiding this comment. I can do this, if it's unclear. In the SSR section on the website, it'd just be useful to say "You will probably need to use our babel plugin's |
||
| </p> | ||
| <p> | ||
| If you want server-side rendering support you can enable it with the{' '} | ||
|
There was a problem hiding this comment. We can cut this short due to the prior intro:
|
||
| <Code>ssr</Code> option: | ||
| </p> | ||
| <CodeBlock code={ssr} language="node" /> | ||
| </SectionLayout> | ||
| <SectionLayout sub title="Better debugging"> | ||
| <p> | ||
| This babel plugin adds the components' name to the class name attached | ||
|
There was a problem hiding this comment.
Also maybe we should mention that it sets a There was a problem hiding this comment.
There was a problem hiding this comment. Well, that sounds a bit wrong ^^" Maybe more like:
(We can't say "DOM node" since it might also be passed to a component) |
||
| to the DOM node. In your browsers DevTools you'll see:{' '} | ||
|
|
||
| <Code> | ||
| <button class="sc-Button-asdf123 asdf123" /> | ||
| </Code>{' '} | ||
| instead of just <Code><button class="asdf123" /></Code>. | ||
| </p> | ||
| <p> | ||
| This also adds support for showing your components' real name in the | ||
| React DevTools. They will normally show{' '} | ||
| <Code><styled.button></Code> for all of your components, but with | ||
|
There was a problem hiding this comment. The examples here are nice, but they're missing reference code. It should probably intro with:
|
||
| this plugin they show <Code><MyButton /></Code>. | ||
| </p> | ||
| <p> | ||
| This makes it easier to find your components and to figure out where | ||
| they live in your app. | ||
| </p> | ||
| <p> | ||
| If you don't need this feature, you can disable it with the{' '} | ||
| <Code>displayName</Code> option: | ||
| </p> | ||
| <CodeBlock code={displayName} language="node" /> | ||
| </SectionLayout> | ||
| <SectionLayout sub title="Preprocessing"> | ||
| <Note> | ||
| This is experimental and we don't yet know of all limitations and bugs! | ||
| Consider this non-production ready for now. ⚠️ | ||
| </Note> | ||
| <p> | ||
| This plugin preprocesses your styles with stylis and uses the{' '} | ||
| <Code>no-parser.js</Code> entrypoint on styled-components. | ||
| </p> | ||
| <p> | ||
| This effectively removes stylis from your runtime bundle and should | ||
| slightly improve runtime performance and shrink your bundle size. | ||
| </p> | ||
| <p> | ||
| It automatically disables the <Code>minify</Code> option, since stylis | ||
| already does some minification on your CSS. | ||
| </p> | ||
| <p> | ||
| You can enable preprocessing with the <Code>preprocess</Code> option: | ||
| </p> | ||
| <CodeBlock code={preprocess} language="node" /> | ||
| </SectionLayout> | ||
| <SectionLayout sub title="Preprocessing"> | ||
|
|
||
| <Note> | ||
| This option is turned on by default! If you experience mangled CSS | ||
|
There was a problem hiding this comment. We can lose the exclamation mark here |
||
| results, turn it off and open an issue please. | ||
| </Note> | ||
| <p> | ||
| This plugin minifies your styles in the tagged template literals, giving | ||
| you big bundle size savings. (note that you will not see the effect of | ||
|
There was a problem hiding this comment. We can lose the parantheses here |
||
| minification in generated <Code><style></Code> tags, it solely | ||
| affects the style strings inside your JS bundle) | ||
| </p> | ||
| <Note> | ||
| This operation may potentially break your styles in some rare cases, so | ||
| we recommend to keep this option enabled in development if it's enabled | ||
| in the production build. | ||
| </Note> | ||
| <p> | ||
| You can disable minification with the <Code>minify</Code> option: | ||
| </p> | ||
| <CodeBlock code={minify} language="node" /> | ||
| <p> | ||
| We also transpile <Code>styled-components</Code> tagged template | ||
|
There was a problem hiding this comment. This should go into a new section, since it's a separate option actually. There was a problem hiding this comment. What should go in this section ? Just this paragraph ? There was a problem hiding this comment. Yea, this entire part about the template string transpilation |
||
| literals down to a smaller representation than what Babel normally does, | ||
| because <Code>styled-components</Code> template literals don't need to | ||
| be 100% spec compliant. see{' '} | ||
| <a href="https://github.com/styled-components/babel-plugin-styled-components/blob/master/minification.md"> | ||
|
There was a problem hiding this comment. The link here can be swapped out for a link to our "Tagged Template Literals" section. Also there's a trailing closed parenthesis below. |
||
| minification.md | ||
| </a>{' '} | ||
| for more information about that) You can use the | ||
| <Code>transpileTemplateLiterals</Code> option to turn this feature off. | ||
| </p> | ||
| </SectionLayout> | ||
| </SectionLayout>; | ||
|
|
||
| export default BabelPlugin; | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can leave out "when using styled-components" as that's quite obvious on the site. But we should add a paragraph that it's only for the web, not for React Native
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done 🎉