{"id":21363715,"url":"https://github.com/mikey-t/swig","last_synced_at":"2026-03-16T03:31:55.918Z","repository":{"id":191247998,"uuid":"683907429","full_name":"mikey-t/swig","owner":"mikey-t","description":"Swig is a simple CLI tool for automating dev workflows via compositions of series and parallel tasks.","archived":false,"fork":false,"pushed_at":"2024-03-20T20:38:13.000Z","size":881,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-21T14:24:35.211Z","etag":null,"topics":["automation","cli","dev-workflow","gulp-alternative","parallel","series","task-runner"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikey-t.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-28T03:21:04.000Z","updated_at":"2023-09-18T06:12:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"ba912321-24a8-4278-aa29-b79f061c849c","html_url":"https://github.com/mikey-t/swig","commit_stats":{"total_commits":28,"total_committers":1,"mean_commits":28.0,"dds":0.0,"last_synced_commit":"88b705b3a4794031f8ca1cdc4dae1c224344d76e"},"previous_names":["mikey-t/swig"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikey-t%2Fswig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikey-t%2Fswig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikey-t%2Fswig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikey-t%2Fswig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikey-t","download_url":"https://codeload.github.com/mikey-t/swig/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243836029,"owners_count":20355616,"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":["automation","cli","dev-workflow","gulp-alternative","parallel","series","task-runner"],"created_at":"2024-11-22T06:20:57.275Z","updated_at":"2026-03-16T03:31:55.910Z","avatar_url":"https://github.com/mikey-t.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# swig\n\nSwig is a simple CLI tool for automating dev workflows via compositions of series and parallel tasks.\n\nWrite simple javascript or typescript functions and easily execute them in a shell in your project's root directory.\n\nFast. Simple. Convenient.\n\n## Pre-requisites\n\nNode.js \u003e= 16 (version 20 is recommended)\n\n## Why Swig Instead of Gulp?\n\nWhy recreate the \"series\", \"parallel\" and \"task runner\" functionality that Gulp already has? Gulp is great, but I wanted to be able to customize how it works, strip out all the noise and add the ability to use a variety of javascript/typescript flavors with little or no extra setup required.\n\n## Typescript Quick Start\n\nSwig does not require typescript, but it is the recommended approach. For instructions on quickly setting up a new project that uses swig with typescript, see [Swig Typescript Quick Start](./docs/SwigTypescriptQuickStart.md) (or simply run `npx swig-cli-init@latest` in your target directory).\n\nFor general getting started steps, continue below.\n\n## Getting Started\n\n- (Optional) Install `swig-cli` globally for convenient shortened commands and much faster task execution (no initial delay from npm/npx):\n  ```bash\n  # With npm:\n  npm i -g swig-cli@latest\n\n  # OR with pnpm:\n  pnpm i -g swig-cli@latest\n  ```\n- Install `swig-cli` package as a dev dependency so you can import `series` and `parallel` in your swigfile:\n  ```bash\n  npm i -D swig-cli\n  ```\n\n- Create a `swigfile` in the root of your project, such as `swigfile.js` (see [Swigfile Syntax Options Matrix](#swigfile-syntax-options-matrix))\n- Add some tasks to your swigfile (see [Series, Parallel and Composability Example](#series-parallel-and-composability-example))\n- List detected tasks from your swigfile (exported functions):\n  ```bash\n  # Global swig-cli install\n  swig\n\n  # OR local swig-cli install\n  npx swig\n  \n  # OR local swig-cli install with pnpm\n  pnpm exec swig\n  ```\n- Run a task:\n  ```bash\n  # Global swig-cli install\n  swig yourTask\n\n  # OR local swig-cli install\n  npx swig yourTask\n  \n  # OR local swig-cli install with pnpm\n  pnpm exec swig yourTask\n  ```\n\n## Swigfile Syntax Options Matrix\n\nYour `swigfile` can be one of the following:\n\n- `swigfile.cjs`\n- `swigfile.mjs`\n- `swigfile.js`\n- `swigfile.ts`\n\nIf there are multiple swigfiles in your project directory, swig will use the first one it finds, using the order above. The following shows the various options for your swigfile file extension, package.json `type` and javascript/typescript syntax flavor to use.\n\n| Swigfile | package.json `type` | Syntax              | Notes |\n|----------|---------------------|---------------------|-------|\n| `.js`    | module              | ESM                 |       |\n| `.js`    | commonjs            | CommonJS            |       |\n| `.cjs`   | any                 | CommonJS            |       |\n| `.mjs`   | any                 | ESM                 |       |\n| `.ts`    | commonjs            | CommonJS | Must have valid `tsconfig.json` options. Must use `ts-node` and NOT `tsx` for CommonJS. |\n| `.ts`    | module              | ESM                 | Must have valid `tsconfig.json` options. Must have either `tsx` or `ts-node` installed. |\n\nIf using typescript:\n\n- You must install either `tsx` or `ts-node` as a dev dependency in your project. These are Node typescript loaders that allow immediate execution of typescript without a transpilation step. Note that `tsx` seems to have fewer issues than `ts-node`, and is much faster. You can install one of these by running `npm i -D tsx` OR `npm i -D ts-node`.\n- In a typescript project where the package.json is set to CommonJS, you will need to use `ts-node` and NOT `tsx`\n- Your `tsconfig.json` needs to have settings that match your `package.json` type. For example, if you have your `package.json` type field set to `module`, then your `tsconfig.json` needs to have a `module` setting of \"ES2020\" or \"ESNext\" (something that supports ESM). See [Swig Typescript Quick Start](./docs/SwigTypescriptQuickStart.md) for an example `tsconfig.json` file.\n- If using `ts-node`, speed up execution time by configuring it to skip type checking (this is only required for NodeJS version 18.19 and above):\n  ```json\n  \"ts-node\": {\n    \"transpileOnly\": true\n  }\n  ```\n- Make sure your `tsconfig.json` has your `swigfile.ts` in it's `include` section in order to get IDE support\n- If using eslint, ensure that your `swigfile.ts` is included in files that it checks\n- If you're using swig to manage a typescript project and have conflicting tsconfig.json settings, consider using a separate file for your build, like `tsconfig.build.json` and build with something like `tsc --p tsconfig.build.json` (or alternatively, you could use another directory for swig other than your project's root directory)\n\n## Series, Parallel and Composability Example\n\nA dev task like `build` might have several steps where some steps can happen in parallel and others must happen sequentially. So we define each of the steps as functions and compose them into an exported task we're calling simply `build`:\n\nSample swigfile contents:\n```JavaScript\nasync function buildPrep() {...}\nasync function buildServer() {...}\nasync function buildClient() {...}\nasync function postBuild() {...}\n\nexport const build = series(buildPrep, parallel(buildClient, buildServer), postBuild)\n```\n\nAnd then we can run it with :\n```javascript\n// Global swig-cli install\nswig build\n\n// OR local swig-cli install\nnpx swig build\n\n// OR local swig-cli install with pnpm\npnpm exec swig build\n```\n\n## Example Projects\n\nSee [dotnet-react-sandbox](https://github.com/mikey-t/dotnet-react-sandbox) and it's use of [swig-cli-modules](https://github.com/mikey-t/swig-cli-modules) to encapsulate tasks for projects that use it as a template.\n\n## Compatibility\n\n### NodeJS Version Support\n\nNode.js versions \u003e= 16 are supported.\n\nTested Node.js versions:\n- 16.20.2\n- 18.16.1\n- 18.19.0\n- 20.19.2\n- 22.16.0\n- 24.1.0\n\n**Important**: NodeJS and/or tsx has a bug that prevents swig from working with tsx for 18.17.x and 18.18.x versions. If you want to use the tsx variant of swig and have one of those versions, you'll need to either downgrade to 18.16.x (or below) or upgrade to 18.19.x (or above).\n\n### Optional dependencies\n\nLatest known working versions of optional dependencies for typescript variant projects:\n- typescript: 5.9.3\n- [tsx](https://github.com/privatenumber/tsx): 4.21.0\n- [ts-node](https://github.com/TypeStrong/ts-node): 10.9.2\n\n## Additional Documentation\n\n- [./docs/SwigSupplementalDocumentation.md](./docs/SwigSupplementalDocumentation.md)\n- [./docs/SwigDevNotes.md](./docs/SwigDevNotes.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikey-t%2Fswig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikey-t%2Fswig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikey-t%2Fswig/lists"}