From 33fea5f8af8e64f6bdfe6fa230bdf63a5fc18eea Mon Sep 17 00:00:00 2001 From: Sara Vieira Date: Sun, 23 Jul 2017 19:27:52 +0100 Subject: [PATCH 1/9] add babel plugin docs --- components/advanced/babel-plugin.js | 165 ++++++++++++++++++++++++++++ pages/docs.json | 75 ++++++++----- pages/docs/advanced.js | 34 +++--- 3 files changed, 231 insertions(+), 43 deletions(-) create mode 100644 components/advanced/babel-plugin.js diff --git a/components/advanced/babel-plugin.js b/components/advanced/babel-plugin.js new file mode 100644 index 00000000..90db7ce1 --- /dev/null +++ b/components/advanced/babel-plugin.js @@ -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 = () => + +

+ This plugin adds support for server-side rendering, for minification of + styles and gives you a nicer debugging experience when using{' '} + styled-components. +

+

Usage

+ +

+ Then in your babel configuration (probably .babelrc): +

+ + + This option is turned off by default +

+ By adding a unique identifier to every styled component this plugin + 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 styled-components React will complain. +

+

+ If you want server-side rendering support you can enable it with the{' '} + ssr option: +

+ + + +

+ This babel plugin adds the components' name to the class name attached + to the DOM node. In your browsers DevTools you'll see:{' '} + + <button class="sc-Button-asdf123 asdf123" /> + {' '} + instead of just <button class="asdf123" />. +

+

+ This also adds support for showing your components' real name in the + React DevTools. They will normally show{' '} + <styled.button> for all of your components, but with + this plugin they show <MyButton />. +

+

+ This makes it easier to find your components and to figure out where + they live in your app. +

+

+ If you don't need this feature, you can disable it with the{' '} + displayName option: +

+ + + + + This is experimental and we don't yet know of all limitations and bugs! + Consider this non-production ready for now. ⚠️ + +

+ This plugin preprocesses your styles with stylis and uses the{' '} + no-parser.js entrypoint on styled-components. +

+

+ This effectively removes stylis from your runtime bundle and should + slightly improve runtime performance and shrink your bundle size. +

+

+ It automatically disables the minify option, since stylis + already does some minification on your CSS. +

+

+ You can enable preprocessing with the preprocess option: +

+ + + + + This option is turned on by default! If you experience mangled CSS + results, turn it off and open an issue please. + +

+ 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 + minification in generated <style> tags, it solely + affects the style strings inside your JS bundle) +

+ + 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. + +

+ You can disable minification with the minify option: +

+ +

+ We also transpile styled-components tagged template + literals down to a smaller representation than what Babel normally does, + because styled-components template literals don't need to + be 100% spec compliant. see{' '} + + minification.md + {' '} + for more information about that) You can use the + transpileTemplateLiterals option to turn this feature off. +

+ + ; + +export default BabelPlugin; diff --git a/pages/docs.json b/pages/docs.json index 8a9bafbc..374d315f 100644 --- a/pages/docs.json +++ b/pages/docs.json @@ -6,69 +6,94 @@ "sections": [ { "title": "Motivation" - }, { + }, + { "title": "Installation" - }, { + }, + { "title": "Getting Started" - }, { + }, + { "title": "Passed props" - }, { + }, + { "title": "Adapting based on props" - }, { + }, + { "title": "Styling any components" - }, { + }, + { "title": "Extending styles" - }, { + }, + { "title": "Attaching additional props" - }, { + }, + { "title": "Animations" - }, { + }, + { "title": "React Native" } ] - }, { + }, + { "title": "Advanced", "pathname": "advanced", "sections": [ { "title": "Theming" - }, { + }, + { "title": "Refs" - }, { + }, + { "title": "Security" - }, { + }, + { "title": "Existing CSS" - }, { + }, + { "title": "Media Templates" - }, { + }, + { "title": "Tagged Template Literals" - }, { + }, + { "title": "Server Side Rendering" + }, + { + "title": "Babel Plugin" } ] - }, { + }, + { "title": "API Reference", "pathname": "api", "sections": [ { "title": "Primary" - }, { + }, + { "title": "Helpers" - }, { + }, + { "title": "Supported CSS" - }, { + }, + { "title": "Flow" - }, { + }, + { "title": "TypeScript" } ] - }, { + }, + { "title": "FAQs", "pathname": "faqs", "sections": [ - {"title": "Can I nest rules?"}, - {"title": "Can I refer to other components?"}, - {"title": "Can I use css frameworks?"} + { "title": "Can I nest rules?" }, + { "title": "Can I refer to other components?" }, + { "title": "Can I use css frameworks?" } ] } ] diff --git a/pages/docs/advanced.js b/pages/docs/advanced.js index 3ec6280f..d28f91bd 100644 --- a/pages/docs/advanced.js +++ b/pages/docs/advanced.js @@ -1,16 +1,17 @@ -import React from 'react' -import DocsLayout from '../../components/DocsLayout' -import NextPage from '../../components/NextPage' +import React from 'react'; +import DocsLayout from '../../components/DocsLayout'; +import NextPage from '../../components/NextPage'; -import Theming from '../../components/advanced/theming' -import Refs from '../../components/advanced/refs' -import Security from '../../components/advanced/security' -import ExistingCSS from '../../components/advanced/existing-css' -import MediaTemplates from '../../components/advanced/media-templates' -import TaggedTemplateLiterals from '../../components/advanced/tagged-template-literals' -import ServerSideRendering from '../../components/advanced/server-side-rendering' +import Theming from '../../components/advanced/theming'; +import Refs from '../../components/advanced/refs'; +import Security from '../../components/advanced/security'; +import ExistingCSS from '../../components/advanced/existing-css'; +import MediaTemplates from '../../components/advanced/media-templates'; +import TaggedTemplateLiterals from '../../components/advanced/tagged-template-literals'; +import ServerSideRendering from '../../components/advanced/server-side-rendering'; +import BabelPlugin from '../../components/advanced/babel-plugin'; -const Advanced = () => ( +const Advanced = () => @@ -19,12 +20,9 @@ const Advanced = () => ( + - - -) + + ; -export default Advanced +export default Advanced; From b6acb4696d02fde25b434727b3fedae3954f7875 Mon Sep 17 00:00:00 2001 From: Sara Vieira Date: Sun, 23 Jul 2017 19:28:34 +0100 Subject: [PATCH 2/9] update tests --- .../NavBar/__snapshots__/Menu.spec.js.snap | 10 ++++++++++ .../NavBar/__snapshots__/index.spec.js.snap | 16 ++++++++++++++++ .../__snapshots__/DocsLayout.spec.js.snap | 16 ++++++++++++++++ 3 files changed, 42 insertions(+) diff --git a/test/components/NavBar/__snapshots__/Menu.spec.js.snap b/test/components/NavBar/__snapshots__/Menu.spec.js.snap index aa226dd4..3d46b732 100644 --- a/test/components/NavBar/__snapshots__/Menu.spec.js.snap +++ b/test/components/NavBar/__snapshots__/Menu.spec.js.snap @@ -273,6 +273,16 @@ exports[`Menu renders correctly 1`] = ` Server Side Rendering +
+ + Babel Plugin + +
+ +
+ + + Babel Plugin + + +
+
+ +
+ + + Babel Plugin + + +
+ Date: Mon, 24 Jul 2017 00:19:58 +0100 Subject: [PATCH 3/9] fix typos --- components/advanced/babel-plugin.js | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/components/advanced/babel-plugin.js b/components/advanced/babel-plugin.js index 90db7ce1..17a0b800 100644 --- a/components/advanced/babel-plugin.js +++ b/components/advanced/babel-plugin.js @@ -58,15 +58,14 @@ const BabelPlugin = () =>

This plugin adds support for server-side rendering, for minification of - styles and gives you a nicer debugging experience when using{' '} - styled-components. + styles and gives you a nicer debugging experience.

-

Usage

- -

- Then in your babel configuration (probably .babelrc): -

- + +

Install the babel-plugin first:

+ +

Then add it to your babel configuration like so:

+ + This option is turned off by default

From 028cef82fce79f798f339bf96f0d791753d275f5 Mon Sep 17 00:00:00 2001 From: Sara Vieira Date: Mon, 24 Jul 2017 00:24:24 +0100 Subject: [PATCH 4/9] fix typos --- components/advanced/babel-plugin.js | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/components/advanced/babel-plugin.js b/components/advanced/babel-plugin.js index 17a0b800..73bdba27 100644 --- a/components/advanced/babel-plugin.js +++ b/components/advanced/babel-plugin.js @@ -72,18 +72,17 @@ const BabelPlugin = () => By adding a unique identifier to every styled component this plugin 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 styled-components React will complain. + server-side render styled-components React will complain.

- If you want server-side rendering support you can enable it with the{' '} - ssr option: + You can enable it with the ssr option:

- This babel plugin adds the components' name to the class name attached - to the DOM node. In your browsers DevTools you'll see:{' '} + This options adds the components' name and displayName to the class name + attached to the DOM node. In your browser's DevTools you'll see:{' '} <button class="sc-Button-asdf123 asdf123" /> {' '} From cf566a7144137ad06ac3c8758a436138ed497f41 Mon Sep 17 00:00:00 2001 From: Sara Vieira Date: Mon, 24 Jul 2017 00:26:18 +0100 Subject: [PATCH 5/9] fix typos --- components/advanced/babel-plugin.js | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/components/advanced/babel-plugin.js b/components/advanced/babel-plugin.js index 73bdba27..1fb53a9d 100644 --- a/components/advanced/babel-plugin.js +++ b/components/advanced/babel-plugin.js @@ -126,16 +126,14 @@ const BabelPlugin = () =>

- + - This option is turned on by default! If you experience mangled CSS + This option is turned on by default. If you experience mangled CSS results, turn it off and open an issue please.

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 - minification in generated <style> tags, it solely - affects the style strings inside your JS bundle) + you big bundle size savings.

This operation may potentially break your styles in some rare cases, so From ad8c1c1f4561e8543808a53957677a3525cf8fb1 Mon Sep 17 00:00:00 2001 From: Sara Vieira Date: Mon, 24 Jul 2017 12:38:40 +0100 Subject: [PATCH 6/9] fix typos --- components/advanced/babel-plugin.js | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/components/advanced/babel-plugin.js b/components/advanced/babel-plugin.js index 1fb53a9d..548231b0 100644 --- a/components/advanced/babel-plugin.js +++ b/components/advanced/babel-plugin.js @@ -90,9 +90,11 @@ const BabelPlugin = () =>

This also adds support for showing your components' real name in the - React DevTools. They will normally show{' '} - <styled.button> for all of your components, but with - this plugin they show <MyButton />. + React DevTools. Consider writing a styled component that renders a{' '} + button element, called MyButton. It will + normally show up as <styled.button> for all of your + components, but with this plugin they show{' '} + <MyButton />.

This makes it easier to find your components and to figure out where From 6b4bf98fb3ed105b6e055900d082722a6141eddf Mon Sep 17 00:00:00 2001 From: Sara Vieira Date: Mon, 24 Jul 2017 12:45:18 +0100 Subject: [PATCH 7/9] fix typos --- components/advanced/babel-plugin.js | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/components/advanced/babel-plugin.js b/components/advanced/babel-plugin.js index 548231b0..2cd5215e 100644 --- a/components/advanced/babel-plugin.js +++ b/components/advanced/babel-plugin.js @@ -54,6 +54,16 @@ const minify = ` } `.trim(); +const transpilation = ` +{ + "plugins": [ + ["styled-components", { + "transpileTemplateLiterals": false + }] + ] +} +`.trim(); + const BabelPlugin = () =>

@@ -146,17 +156,18 @@ const BabelPlugin = () => You can disable minification with the minify option:

+ +

We also transpile styled-components tagged template literals down to a smaller representation than what Babel normally does, because styled-components template literals don't need to be 100% spec compliant. see{' '} - - minification.md - {' '} - for more information about that) You can use the + Tagged Template Literals for + more information about that) You can use the {' '} transpileTemplateLiterals option to turn this feature off.

+ ; From 13c7ee38c3eb1b20baa6a469136f53b56f77014d Mon Sep 17 00:00:00 2001 From: Sara Vieira Date: Tue, 25 Jul 2017 21:40:28 +0100 Subject: [PATCH 8/9] update link --- components/advanced/babel-plugin.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/components/advanced/babel-plugin.js b/components/advanced/babel-plugin.js index 2cd5215e..57cb4f6f 100644 --- a/components/advanced/babel-plugin.js +++ b/components/advanced/babel-plugin.js @@ -3,6 +3,7 @@ import SectionLayout from '../SectionLayout'; import CodeBlock from '../CodeBlock'; import Code from '../Code'; import Note from '../Note'; +import Link from '../Link' const installNPM = ` npm install --save-dev babel-plugin-styled-components @@ -163,7 +164,7 @@ const BabelPlugin = () => literals down to a smaller representation than what Babel normally does, because styled-components template literals don't need to be 100% spec compliant. see{' '} - Tagged Template Literals for + Tagged Template Literals for more information about that) You can use the {' '} transpileTemplateLiterals option to turn this feature off.

From 8652658c355a6d8c53f710e6e8f82f7b147d7207 Mon Sep 17 00:00:00 2001 From: Sara Vieira Date: Tue, 25 Jul 2017 22:15:07 +0100 Subject: [PATCH 9/9] make link pretty --- components/advanced/babel-plugin.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/advanced/babel-plugin.js b/components/advanced/babel-plugin.js index 57cb4f6f..c9b82c45 100644 --- a/components/advanced/babel-plugin.js +++ b/components/advanced/babel-plugin.js @@ -164,7 +164,7 @@ const BabelPlugin = () => literals down to a smaller representation than what Babel normally does, because styled-components template literals don't need to be 100% spec compliant. see{' '} - Tagged Template Literals for + Tagged Template Literals for more information about that) You can use the {' '} transpileTemplateLiterals option to turn this feature off.