Merge pull request #629 from gregberge/rewriting-docs

docs: rewriting

packages/babel-plugin-transform-svg-component/src/index.ts

@@ -10,7 +10,7 @@ import type { Options } from './types'
 import { defaultTemplate } from './defaultTemplate'
 import { getVariables } from './variables'
 
-export type { Options } from './types'
+export type { Options, Template } from './types'
 
 const plugin = (_: ConfigAPI, opts: Options) => {
   const template = opts.template || defaultTemplate

website/pages/docs/cli.mdx

@@ -1,109 +1,114 @@
 ---
 section: Usage
-title: CLI
-order: 10
+title: Command Line
+order: 20
 ---
 
-# CLI
+# Command Line
 
-SVGR can be run from the CLI. Run it without argument to see the [options](/docs/options).
+Use SVGR from command line to transform a single file or a whole directory.
 
 <carbon-ad />
 
 ## Install
 
-```bash
-npm install @svgr/cli --save-dev
+Depending you usage, you can install `@svgr/cli` locally in your project:
+
+```sh
+npm install --save-dev @svgr/cli
 # or use yarn
-yarn add @svgr/cli --dev
+yarn add --dev @svgr/cli
 ```
 
-## Usage
+or use it on the fly using `npx @svgr/cli`.
 
-```bash
-npx @svgr/cli icons/clock-icon.svg
-```
+## Options
 
-## Recipes
+All [SVGR options](https://react-svgr.com/docs/options/) are available from command line or in configuration. Command line options have precedence over config file options.
 
-### Transform a whole directory
+## Transform a single file
 
-A whole directory can be processed, all SVG files (matching `.svg` or `.SVG`)
-are transformed into React components.
+### From file
+
+Transforms a single file by specifying file as the single argument.
 
 ```sh
-# Usage: npx @svgr/cli [-d out-dir] [--ignore-existing] [src-dir]
-$ npx @svgr/cli -d icons icons
-icons/web/clock-icon.svg -> icons/web/ClockIcon.js
-icons/web/wifi-icon.svg -> icons/web/WifiIcon.js
-icons/spinner/cog-icon.svg -> icons/spinner/CogIcon.js
-icons/spinner/spinner-icon.svg -> icons/spinner/SpinnerIcon.js
+npx @svgr/cli -- icons/clock-icon.svg
 ```
 
-> Add `--ignore-existing` to avoid overriding existing files.
+### From standard input
 
-### Use stdin
+`@svgr/cli` supports standard input, just redirect file contents using `<` operator.
 
-```
-$ npx @svgr/cli < icons/web/wifi-icon.svg
+```sh
+npx @svgr/cli < icons/clock-icon.svg
 ```
 
-### Use stdin / stdout
+### Output the result in another file
 
-```
-$ npx @svgr/cli < icons/web/wifi-icon.svg > icons/web/WifiIcon.js
-```
+You can easily create another file using `>` operator.
 
-### Transform icons
+```sh
+npx @svgr/cli -- icons/clock-icon.svg > dist/ClockIcon.js
+```
 
-To create icons, two options are important:
+## Transform a whole directory
 
-- `--icon`: viewBox is preserved and SVG inherits text size
-- `--replace-attr-values "#000=currentColor"`: "#000" is replaced by
-  "currentColor" and SVG inherits text color
+Transforms a whole directory using `--out-dir` option. All SVG presents in this directory tree are transformed into React components.
 
-```
-$ npx @svgr/cli --icon --replace-attr-values "#000=currentColor" my-icon.svg
+```sh
+# Usage: npx @svgr/cli [--out-dir dir] [--ignore-existing] [src-dir]
+$ npx @svgr/cli --out-dir dist -- icons
+icons/web/clock-icon.svg -> dist/web/ClockIcon.js
+icons/web/wifi-icon.svg -> dist/web/WifiIcon.js
+icons/spinner/cog-icon.svg -> dist/spinner/CogIcon.js
+icons/spinner/spinner-icon.svg -> dist/spinner/SpinnerIcon.js
 ```
 
-> You can replace several values using `,` as separator: `--replace-attr-values "#000=currentColor,#fff=currentColor"`
+### Avoid replacing existing files
 
-## Target React Native
+Even if it is not recommended, you may be tempted to modify generated files. If you do so, you should use the `--ignore-existing` option to avoid replacing existing files.
 
-It is possible to target React Native using [react-native-svg](https://github.com/react-native-community/react-native-svg).
-
-```
-$ npx @svgr/cli --native my-icon.svg
+```sh
+npx @svgr/cli --out-dir dist --ignore-existing -- icons
 ```
 
-## Use a specific template
+### Use a different filename case
 
-You can use a specific template.
+By default, filenames uses "PascalCase", you can specify a different case for generated files using `--filename-case` option.
 
+```sh
+npx @svgr/cli --out-dir dist --filename-case kebab -- icons
 ```
-$ npx @svgr/cli --template path/to/template.js my-icon.svg
+
+### Disable index generation
+
+By default an index is generated, giving you opportunity to import all your components from the directory. If you does not want auto-generated index, turn it off using `--no-index` option.
+
+```sh
+npx @svgr/cli --out-dir dist --no-index -- icons
 ```
 
-An example of template:
+### Use a custom index template
+
+Advanced use cases could lead you to customize the index template. The `--index-template <template>` argument let you specify a custom one.
 
 ```js
-function template(
-  { template },
-  opts,
-  { imports, componentName, props, jsx, exports },
-) {
-  return template.ast`
-    ${imports}
-    const ${componentName} = (${props}) => ${jsx}
-    ${exports}
-  `
+// index-template.js
+const path = require('path')
+
+function defaultIndexTemplate(filePaths) {
+  const exportEntries = filePaths.map((filePath) => {
+    const basename = path.basename(filePath, path.extname(filePath))
+    const exportName = /^\d/.test(basename) ? `Svg${basename}` : basename
+    return `export { default as ${exportName} } from './${basename}'`
+  })
+  return exportEntries.join('\n')
 }
 
-module.exports = template
+module.exports = defaultIndexTemplate
 ```
 
-Template must return a Babel AST, the template function take three arguments:
-
-- `api`: API methods provided by Babel
-- `opts`: SVGR options
-- `values`: Pre-computed values to use (or not) in your templates
+```sh
+npx @svgr/cli  --out-dir dist --index-template index-template.js -- icons
+```

website/pages/docs/custom-templates.mdx

@@ -6,7 +6,7 @@ order: 6
 
 # Custom Templates
 
-Custom templates give you the opportunity to personalize the final generated component by SVGR. In most of case you don't need it, only advanced use-cases require templates.
+Customize template to personalize the result React component.
 
 <carbon-ad />
 
@@ -16,59 +16,45 @@ A custom template takes place in a file that exports a "template function".
 
 This function is called in a babel plugin: `babel-plugin-transform-svg-component` and must returns a Babel AST. If you are not familiar with all Babel stuff, you should read [this guide](https://github.com/jamiebuilds/babel-handbook).
 
-- `api`: The API object returned by Babel
-- `opts`: Options passed to `babel-plugin-transform-svg-component`
-- `astParts`: All pre-compiled parts by SVGR
+- `variables`: All pre-compiled variables by SVGR
   - `componentName`: The component name
   - `props`: The properties
   - `interfaces`: All necessary interfaces (typescript)
   - `imports`: All necessary imports
   - `exports`: The export of the component
   - `jsx`: The JSX part of the component
+- `context`:
+  - `tpl`: A built-in template-tag function to create template
+  - `options`: Options passed to `babel-plugin-transform-svg-component`
 
 The following template is the default template used by SVGR. It is a good idea to start with it:
 
 ```js
-function defaultTemplate(
-  { template },
-  opts,
-  { imports, interfaces, componentName, props, jsx, exports },
-) {
-  const plugins = ['jsx']
-  if (opts.typescript) {
-    plugins.push('typescript')
-  }
-  const typeScriptTpl = template.smart({ plugins })
-  return typeScriptTpl.ast`${imports}
-
-${interfaces}
-
-function ${componentName}(${props}) {
-  return ${jsx};
-}
-${exports}
-  `
+const template = (variables, { tpl }) => {
+  return tpl`
+${variables.imports};
+
+${variables.interfaces};
+
+const ${variables.componentName} = (${variables.props}) => (
+  ${variables.jsx}
+);
+ 
+${variables.exports};
+`
 }
 
-module.exports = defaultTemplate
+module.exports = template
 ```
 
-As you can see, we use [the `template.ast` helper of Babel](https://babeljs.io/docs/en/babel-template#template). This function have to return an AST.
-
 Let's try something very simple. You want to add some PropTypes to your component:
 
 ```js
-function propTypesTemplate(
-  { template },
-  opts,
+const propTypesTemplate = (
   { imports, interfaces, componentName, props, jsx, exports },
-) {
-  const plugins = ['jsx']
-  if (opts.typescript) {
-    plugins.push('typescript')
-  }
-  const typeScriptTpl = template.smart({ plugins })
-  return typeScriptTpl.ast`${imports}
+  { tpl },
+) => {
+  return tpl.ast`${imports}
 import PropTypes from 'prop-types';
 ${interfaces}
 
@@ -94,7 +80,7 @@ As you can see it is very natural, we just add code and use AST parts in the tem
 You can use component template in the CLI:
 
 ```sh
-$ npx @svgr/cli --template template.js my-icon.svg
+npx @svgr/cli --template template.js -- my-icon.svg
 ```
 
 ### Use with config
@@ -134,5 +120,5 @@ module.exports = defaultIndexTemplate
 You can use component template in the CLI:
 
 ```sh
-$ npx @svgr/cli --index-template index-template.js my-icon.svg
+npx @svgr/cli --index-template index-template.js -- my-icon.svg
 ```

website/pages/docs/custom-transformations.mdx

@@ -6,7 +6,7 @@ order: 10
 
 # Custom transformations
 
-SVGR exposes a simple API but it is extendable, you can extend it to create complex SVG transformations.
+Extend the core of SVGR to creates complex transformations.
 
 <carbon-ad />
 

website/pages/docs/ecosystem.mdx

@@ -6,13 +6,14 @@ order: 30
 
 # Ecosystem
 
-This is an incomplete list of awesome things built with svgr. If you have something to share, please submit a PR on [GitHub project](https://github.com/gregberge/svgr).
+This is an incomplete list of awesome things built with SVGR.
 
 <carbon-ad />
 
-## SVGR inside ✨
+## Tools that includes official SVGR support ✨
 
 - [Create React App](https://facebook.github.io/create-react-app/)
+- [Parcel](https://parceljs.org/)
 - [React SSR Setup](https://github.com/manuelbieh/react-ssr-setup)
 - [SVG Gobbler Browser Extension](https://github.com/rossmoody/svg-gobbler)
 
@@ -35,7 +36,12 @@ This is an incomplete list of awesome things built with svgr. If you have someth
 - [@nice-js/svgr-loader](https://www.npmjs.com/package/@nice-js/svgr-loader) - SVGR loader for Nice.js
 - [bs-svgr](https://www.npmjs.com/package/bs-svgr) - SVGR plugin for BuckleScript (Reason)
 - [vite-plugin-svgr](https://github.com/lucsky/vite-plugin-svgr) - SVGR loader for [Vite](https://vitejs.dev/)
+- [SVGR for Figma](https://www.figma.com/community/plugin/749818562498396194/SVG-to-JSX)
+- [esbuild-plugin-svgr](https://github.com/kazijawad/esbuild-plugin-svgr)
 
-## Macros
+## Macros & Babel Presets
 
 - [svgr.macro](https://www.npmjs.com/package/svgr.macro) - Babel macro for SVGR
+- [babel-preset-svgr](https://github.com/birdofpreyru/babel-preset-svgr)
+
+If you have something to share, please submit a PR on [GitHub project](https://github.com/gregberge/svgr).