{"id":17041468,"url":"https://github.com/davestewart/outliner","last_synced_at":"2025-04-12T14:33:12.559Z","repository":{"id":46992039,"uuid":"406764998","full_name":"davestewart/outliner","owner":"davestewart","description":"A node package to outline SVG strokes as fills","archived":false,"fork":false,"pushed_at":"2023-07-28T14:56:32.000Z","size":462,"stargazers_count":38,"open_issues_count":11,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-10T09:12:53.450Z","etag":null,"topics":["design","figma","icons","sketch","sketch-plugin","svg"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davestewart.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-09-15T12:58:05.000Z","updated_at":"2025-03-19T13:55:26.000Z","dependencies_parsed_at":"2022-08-25T15:11:45.529Z","dependency_job_id":null,"html_url":"https://github.com/davestewart/outliner","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davestewart%2Foutliner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davestewart%2Foutliner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davestewart%2Foutliner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davestewart%2Foutliner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davestewart","download_url":"https://codeload.github.com/davestewart/outliner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248581358,"owners_count":21128155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["design","figma","icons","sketch","sketch-plugin","svg"],"created_at":"2024-10-14T09:12:30.059Z","updated_at":"2025-04-12T14:33:12.534Z","avatar_url":"https://github.com/davestewart.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Outliner\n\n![outliner logo](https://raw.githubusercontent.com/davestewart/outliner/master/assets/artwork/outliner-logo.png)\n\n## Intro\n\n### Overview\n\nOutliner is a Node package that converts SVG strokes to outlined fills as a *post-export* process:\n\n![process](https://raw.githubusercontent.com/davestewart/outliner/master/assets/artwork/process.png)\n\nOutliner is designed for:\n\n- icon creators; no more locking in those curves and losing your vector tweaks!\n- developers; work with clean SVG conversions and manipulate attributes in code\n\n### Why outline strokes?\n\nHTML + SVG + CSS is perfect for things like icons, however SVG + CSS may not always provide the intended result as you can see from this [comparison](./demo/comparison.html):  \n\n![comparison](https://raw.githubusercontent.com/davestewart/outliner/master/assets/artwork/comparison.png)\n\nIf your aim is to make colorising your icons predictable, then there are two main options:\n\n- replace SVG colours with the CSS `currentColor` variable\n- outline strokes\n\nUsing `currentColor` is an easy win, but you lose the icon's original color information (so not good for two-color icons). Outlining strokes is a more flexible, reliable, production-ready option.\n\nThe choice is up to you of course!\n\n### Why the \"post-export\" process?\n\nProcessing your SVGs files after they have been exported enables you to keep strokes and retain flexibility within [Figma](https://twitter.com/figmadesign) or [Sketch](https://twitter.com/sketch):\n\n- strokes allow you to adjust widths and corner radii on the fly\n- outlined objects cannot be changed once outlined\n- union operators close open paths (Sketch) or create heavy exports (Figma)\n\n### Are there any drawbacks?\n\nThere are a few things to consider:\n\n1. stroke conversion does not always work first time; you may need to tweak your original vectors; adjusting layer order or redrawing some simple shapes can work. Note that it seems to rarely happen on simple shapes, and there is [a ticket open](https://github.com/davestewart/outliner/issues/1) to look at this again.\n2. some join caps [don't seem to properly convert](https://github.com/davestewart/outliner/blob/main/src/tasks/outline.js#L34), so the package currently forces round caps.\n3. if you want to be sure the graphic you see in your drawing package is the same as the one that is saved to disk, you may want to stick to outlining in your drawing package (though be aware, exported outlines from your package of choice [may be heavier than you expected](https://twitter.com/dave_stewart/status/1437980506205958148)).\n\n## Getting started\n\nTo use Outliner, you will need [Node](https://nodejs.org/en/) and NPM installed.\n\nOnce installed, there are two ways to use Outliner:\n\n- as a **[service](#running-as-a-service)**, where you watch a source folder and convert files as you export them\n- as a **[dependency](#running-as-a-dependency)**, where you use the conversion functions Outliner exposes in your own project\n\nIf you want to run Outliner from anywhere on your machine, install **globally** and run as a **service**.\n\n## Running as a service\n\n### As a global service\n\n\u003e Best for designers working alone\n\nOpen a terminal prompt and install the package globally:\n\n```bash\nnpm install @davestewart/outliner --global\n```\n\nTo start converting, call the `outliner` service passing `source` and (optional) `target` paths:\n\n```\nnode outliner \u003csource\u003e \u003ctarget\u003e\n```\n\nNote:\n\n- paths can be relative or absolute\n- if you omit `target`, your `source` files will overwritten in place\n- To remove `width` and `height` information (so they resize nicely) pass the `--autosize` flag:\n\n```\nnode outliner \u003csource\u003e \u003ctarget\u003e --autosize\n```\n\n### As a project service\n\n\u003e Best for designers working in teams\n\nYou can also run Outliner as a service **within** a JavaScript project.\n\nThis makes it simple for *anyone* who is working with the project source to update assets.\n\nThis time, install Outliner *locally*:\n\n```bash\nnpm install @davestewart/outliner --save-dev\n```\n\nThen, add a script entry to your project's `package.json`, e.g.:\n\n```json\n{\n  \"scripts\": {\n    \"outline-icons\": \"node outliner \u003csource\u003e \u003ctarget\u003e --autosize\"\n  }\n}\n```\n\nYou can then run the Outliner service like so:\n\n```bash\nnpm run outline-icons\n```\n\nOutliner will start and watch the folder you specify in `\u003csource\u003e` and output to `\u003ctarget\u003e`.\n\n### Logging\n\nOnce the service is running, Outliner will start converting files and logging results:\n\n![logging](https://raw.githubusercontent.com/davestewart/outliner/master/assets/artwork/cli.png)\n\nThe service will continue to watch the `source` folder, and any further exports will be detected, converted and logged automatically.\n\nA good terminal should render the paths as clickable links, making it easy to open the updated files.\n\nFor reference, the log states are:\n\n| State     | Description                                                  |\n| --------- | ------------------------------------------------------------ |\n| no file   | the source file did not exist                                |\n| no data   | the source file contained no data                            |\n| no write  | no target file was written, only the output returned (API only) |\n| no change | no change between output and target, so the target was not updated |\n| updated   | the new output was different from the old, so the target was updated |\n| copied    | the source file did not exist in the target folder, so was copied |\n\n## Running as a dependency\n\n\u003e Best for developers who need to manipulate SVGs\n\nOutliner is a typical dependency that you install and use like any other package.\n\nInstall as usual:\n\n```bash\nnpm i @davestewart/outliner --save-dev\n```\n\nThere are two functions exposed:\n\n- `outlineFile()` - loads a file, outlines it, and returns or saves the result\n- `outlineSvg()` - outlines SVG text only\n\nConverting files should be straightforward:\n\n```js\n// import dependencies\nimport { outlineFile, outlineSvg } from '@davestewart/outliner'\n\n// convert a file and save a copy\noutlineFile('./assets/src/star.svg', './assets/trg/star.svg')\n\n// convert a file and save in place\noutlineFile('./assets/src/star.svg')\n\n// get the converted output but don't save\nconst output = outlineFile('./assets/src/star.svg', false)\n\n// convert existing SVG text\nconst output = outlineSvg(input)\n```\n\nNote that you can also pass a couple of extra arguments to:\n\n- change how Outliner behaves\n- log task information\n\nFor example:\n\n```js\n// variables\nconst tasks = ['outline'] // outline but don't strip width and height\nconst log = {}            // object to collect logging info\n\n// convert\noutlineFile('./assets/src/star.svg', './assets/trg/star.svg', tasks, log)\n\n// debug\nconsole.log(log)\n```\n\nThe log object will be populated by each of the tasks that ran:\n\n```\n{\n  paths: 1,\n  autosize: true,\n  state: 'updated'\n}\n```\n\nNote that you can also pass custom functions as `tasks`:\n\n```js\nfunction replaceColor (svg, log) {\n  log.replaceColor = true\n  return svg.replace(/#000000/g, 'currentColor')\n}\n\noutlineSvg(svg, ['outline', replaceColor], log)\n```\n\nCheck the `tests/index.js` file for working code.\n\n## API\n\n#### Outline File\n\n\u003e Outlines a source file and overwrites or writes the results to a new file\n\nSignature:\n\n```ts\noutlineFile(src: string, trg?: string | false | null, tasks?: Array\u003cstring | Function\u003e, log?: object)\n```\n\nParameters:\n\n- `src`: a relative or absolute path to a source folder\n- `trg`: an optional relative or absolute path to a target folder\n  - pass `undefined` to use the same `src` \n  - Pass `false` or `null` to skip writing and just return the output \n- `tasks`: an array of tasks to run, defaults to `['outline', 'autosize']`\n  - string tasks should be one of `'outline'` or`'autosize'`\n  - functions should be of the format `(svg: string, log: object) =\u003e {}: string`  \n- `log`: an optional `{}` object to receive logging information\n\n#### Outline SVG\n\n\u003e Outlines SVG text and returns the result\n\nSignature:\n\n```js\noutlineSvg(svg: string, tasks?: Array\u003cstring | Function\u003e, log?: object)\n```\n\nParameters:\n\n- `svg`: valid SVG text\n- `tasks`: an array of tasks to run, defaults to `['outline', 'autosize']`\n  - string tasks should be one of `'outline'` or`'autosize'`\n  - functions should be of the format `(svg: string, log: object) =\u003e {}: string` \n- `log`: an optional `{}` object to receive logging information\n\n#### State\n\n\u003e An object of constants to compare against\n\nThe `log.state` for each file operation will contain one of these values:\n\n```js\nState.NO_FILE   = 'no file' \nState.NO_DATA   = 'no data' \nState.NO_WRITE  = 'no write' \nState.NO_CHANGE = 'no change' \nState.UPDATED   = 'updated' \nState.COPIED    = 'copied'\n```\n\n## Demos\n\n\u003e If you clone the repo, you will be able to play with the demo.\n\nRun the demo with:\n\n```\nnpm run demo\n```\n\nYou can compare the `source` and `target` output in Figma, Sketch, or a text editor.\n\nIf you want to tweak and re-export the source files, Outliner will pick up any changes and update the target folder each time you export.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavestewart%2Foutliner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavestewart%2Foutliner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavestewart%2Foutliner/lists"}