-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
96c3398
commit 1297662
Showing
1 changed file
with
79 additions
and
44 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,84 +1,119 @@ | ||
| # svgpipe | ||
| # Svgpipe | ||
|
|
||
| A flexible wrapper arround svgo for furher SVG processing or to add addtional files. Svgpipe comes with predefined handlers, but it is easy to create your own. For example, build an icon component based on your SVG files. | ||
| A flexible wrapper arround SVGO to postprocess optimized SVGs. Svgpipe comes with predefined handlers that can be used to create a typed icon-component or similar. But it is easy to create a custom handler. | ||
|
|
||
| ## Installation | ||
|
|
||
| ```bash | ||
| npm i --save-dev svgpipe | ||
| pnpm i -D svgpipe | ||
| pnpm add -D svgpipe | ||
| yarn add -D svgpipe | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| ```bash | ||
| npx svgpipe init | ||
| npx svgpipe run | ||
| ``` | ||
|
|
||
| ### Help | ||
| Create a config file and a folder scaffold. | ||
|
|
||
| ```bash | ||
| npx svgpipe --help | ||
| npx svgpipe init | ||
| ``` | ||
|
|
||
| ## Config | ||
| Drop your SVGs in `./svgpipe/in/<yourFolder>` and update the config. | ||
|
|
||
| ```JavaScript | ||
| // svgpipe.config.ts | ||
| import { defineConfig } from "svgpipe"; | ||
|
|
||
| export default defineConfig({ | ||
| baseOutputDir: "svgpipe", // that's the default | ||
| // You can process multiple folders with svgs (modules) each with its own config | ||
| export Default defineConfig({ | ||
| modules: { | ||
| // Create a module with a predefined handler | ||
| inputFolderName: "css-mask", | ||
| // Or pass options to the predefined handler | ||
| anotherInput: { | ||
| handler: "css-mask" | ||
| prepareName: (name) => "my-" + name | ||
| svgo: { | ||
| // custom config | ||
| config: {}, | ||
| // opt out of the default merge behaviour | ||
| replace: true, | ||
| // print the config to the terminal | ||
| stdout: true | ||
| } | ||
| }, | ||
| // Create your own handler | ||
| oneMoreInput: { | ||
| // load SVGs from "./svgpipe/in/logo and process with 'css-mask' handler" | ||
| logo: "css-mask", | ||
| // load svg from "./svgpipe/in/icon" and apply custom handler | ||
| icon: { | ||
| handler: (conf) => ({}) | ||
| } | ||
| }, | ||
| }); | ||
|
|
||
| ``` | ||
|
|
||
| ## Handlers | ||
| Process SVGs and create files. | ||
|
|
||
| ```bash | ||
| npx svgpipe run | ||
| ``` | ||
|
|
||
| ## Built-in Handlers | ||
|
|
||
| | Name | Output | Note | | ||
| | :------------- | :----------------------------------------------------------------------------------------------------------- | :---------------------------- | | ||
| | `css-mask` | [View](https://github.com/niklas-may/svgpipe/tree/main/src/handler/__test__/snapshots/css-mask.css.txt) | | | ||
| | `vue-css-mask` | [View](https://github.com/niklas-may/svgpipe/tree/main/src/handler/__test__/snapshots/vue-css-mask.vue.txt) | | | ||
| | `vue-inline` | [View](https://github.com/niklas-may/svgpipe/tree/main/src/handler/__test__/snapshots/vue-inline.vue.txt) | Depends on `vite-svg-loader`. | | ||
|
|
||
| ### Built in | ||
| ## Options | ||
|
|
||
| | name | output | note | | ||
| | :------------- | :----------------------------------------------------------------------------------------------------------- | :--------------------------- | | ||
| | `css-mask` | [view](https://github.com/niklas-may/svgpipe/tree/main/src/handler/__test__/snapshots/css-mask.css.txt) | | | ||
| | `vue-css-mask` | [view](https://github.com/niklas-may/svgpipe/tree/main/src/handler/__test__/snapshots/vue-css-mask.vue.txt) | | | ||
| | `vue-inline` | [view](https://github.com/niklas-may/svgpipe/tree/main/src/handler/__test__/snapshots/vue-inline.vue.txt) | depends on `vite-svg-loader` | | ||
| | Property | Type | Default | Description | | ||
| | :--------- | :---------------------------------- | :------------- | -------------------------------------------------------------------------- | | ||
| | `baseIn`? | `string` | ./svgpipe/in | Root folder to find the input SVGs. | | ||
| | `baseOut`? | `string` | ./svgpipe/.out | Root folder for all output files. | | ||
| | `cleanup` | `boolean` | true | Delete files in the output folders that where not part of the current run. | | ||
| | `modules` | `UserModuleConfig` or `HandlerName` | | Config for one set of SVGs. See Handlers. | | ||
|
|
||
| ### Create custom handler | ||
| ### Module | ||
|
|
||
| Implement a `CreateHandler`. This is a function that recieves ervery processed module config and returns a `ISvgHandler`. This has three properties. `onFile`: Will be called for every processed input svg file. Retrun the file if you want to keep it. `onEnd`: Will be called with the `Context` after all svgs are processed. The `Context` provides a type handler that creates a TypeScript type for the module and a corresponding token handler. The last property is the `SvgoConfig`. This can be modified from the user config. | ||
| | Property | Type | Default | Description | | ||
| | :------------ | :------------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------- | | ||
| | `in`? | `string` | {baseIn}/{objectKeyOfModule} | Folder where the SVGs for this module are. If undefined, the module key will be used. | | ||
| | `out`? | `string` | {baseOut} | Folder for ouput. | | ||
| | `typePath`? | `string` | {baseOut}/types | Folder for the TypeScript type file. This has a type with all the SVG names as string literals. | | ||
| | `tokenPath`? | `string` | {baseOut}/token | Folder for the TypeScript token file. This has a variable with an array with all SVG names. | | ||
| | `ignoreBase`? | `boolean` | false | Don't prepend the base path. | | ||
| | `svgo`? | `UserModuleConfig["svgo"]` | {} | SVGO Options. | | ||
|
|
||
| #### SVGO | ||
|
|
||
| | Property | Type | Default | Description | | ||
| | :------------- | :------------------------ | :------ | :---------------------------------------------------------------------- | | ||
| | `config`? | `SvgoConfig` | {} | SVGO Config. | | ||
| | `replace`? | `boolean` | false | Opt out of default config merging. | | ||
| | `stdout`? | `boolean` | false | Print the config to the console. | | ||
| | `prepareName`? | `(str: string) => string` | | Modify the svg file name. The name will be used for types, classes e.g. | | ||
| | `handler` | `CreateHandler` | | The actual svg handle. | | ||
|
|
||
| ## Custom Handler | ||
|
|
||
| ```TypeScript | ||
| import type { CreateHandler } from "svgpipe" | ||
| import { type CreateHandler, File } from "svgpipe" | ||
|
|
||
| const myHanlder: CreateHandler = (conf) => ({ | ||
| const myHanlder: CreateHandler = (moduleConfig) => ({ | ||
| onFile: (svgFile) => { | ||
| // Do what ever you want. Return the file to keep it. | ||
| return svgFile | ||
| }, | ||
| onEnd: (context) => { | ||
| // Do cleanup work or create addtional files | ||
| const myFile = new File() | ||
| return [myFile] | ||
| } | ||
| config: { | ||
| multipass: true | ||
| }, | ||
| onFile: (svgFile) => svgFile, | ||
| onEnd: ctx => [] | ||
| }) | ||
| ``` | ||
|
|
||
| Implement a `CreateHandler`. This is a function that recieves every processed module config and returns a `ISvgHandler`. | ||
|
|
||
| ### `onFile`: | ||
|
|
||
| Will be called for every processed input svg file. Retrun the file if you want to keep it. | ||
|
|
||
| ### `onEnd`: | ||
|
|
||
| Will be called with the `Context` after all SVGs are processed. Return nothing or `IFile[]` with additional files that you want to write to disk. `Context` provides a type handler that creates a TypeScript type file for the module and a corresponding token handler. | ||
|
|
||
| ### `config`. | ||
|
|
||
| The default SVGO config that should be used. This can be modified from the user config. | ||
|
|
||
| All built-in handlers are exported in case you want to extend one. |