{"id":16295262,"url":"https://github.com/seia-soto/userscript-composer","last_synced_at":"2026-04-26T20:31:37.092Z","repository":{"id":103812096,"uuid":"524490277","full_name":"seia-soto/userscript-composer","owner":"seia-soto","description":"Ability to compose userscripts for unified distribution.","archived":false,"fork":false,"pushed_at":"2022-08-15T06:37:52.000Z","size":139,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-04T17:15:32.311Z","etag":null,"topics":["build-tool","userscript"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/userscript-composer","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seia-soto.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":"2022-08-13T19:30:38.000Z","updated_at":"2024-06-14T02:29:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"c8576d54-c7e8-4847-98d0-ce80f5633a64","html_url":"https://github.com/seia-soto/userscript-composer","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/seia-soto/userscript-composer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seia-soto%2Fuserscript-composer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seia-soto%2Fuserscript-composer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seia-soto%2Fuserscript-composer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seia-soto%2Fuserscript-composer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seia-soto","download_url":"https://codeload.github.com/seia-soto/userscript-composer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seia-soto%2Fuserscript-composer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32312209,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T19:15:34.056Z","status":"ssl_error","status_checked_at":"2026-04-26T19:15:15.467Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["build-tool","userscript"],"created_at":"2024-10-10T20:18:13.591Z","updated_at":"2026-04-26T20:31:37.072Z","avatar_url":"https://github.com/seia-soto.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# userscript-composer\n\nAbility to compose userscripts for unified distribution.\n\n**Table of Contents**\n\n- [userscript-composer](#userscript-composer)\n- [Overview](#overview)\n  - [Quickstart](#quickstart)\n  - [Workaround](#workaround)\n- [Usage](#usage)\n  - [Commands](#commands)\n    - [`userscript-composer init`](#userscript-composer-init)\n    - [`userscript-composer build`](#userscript-composer-build)\n    - [`userscript-composer batch`](#userscript-composer-batch)\n    - [`userscript-composer unify`](#userscript-composer-unify)\n  - [API](#api)\n- [Development](#development)\n\n---\n\n# Overview\n\nElegant userscript build tool with:\n- ✨ TypeScript support\n- 💫 JSX support\n- 🔗 Bundling with dependencies\n- 📋 Composing scripts\n- 🙃 Standalone bundling\n\nuserscript-composer is built top on **cac, esbuild, picomatch, and terser** to give you best development experience and production output.\nThanks to authors and contributors of those packages as userscript-composer could not exists without their technologies.\n\n## Quickstart\n\nTo install quick as possible, you can use following commands to initiate building.\n\n```sh\nmkdir userscript-composer-playground\ncd userscript-composer-playground\n\nmkdir scripts\ntouch header.txt # header.txt will be prepended to unified output\n\nnpm init -y\nnpm install -g userscript-composer\n\n# Or you may use GitHub for latest versions which might have bug fixes for NPM versions\nnpm install -g git+https://github.com/seia-soto/userscript-composer.git\n```\n\nThe script above will install userscript-composer as global package.\nIf you don't want to install package as global, you can remove `-g` flag from the command and add following entry to `script` in `package.json`.\n\n```json\n{\n  \"scripts\": {\n    \"composer\": \"userscript-composer\"\n  }\n}\n```\n\nNow, bomb!\n\n```sh\nnpm run composer -h\n```\n\n## Workaround\n\nThe reason of userscript-composer to exist is automating the build process of multiple userscripts into one userscript.\nTo reach the goal, I decided to use transpilers and bundlers to build userscripts, and this made userscript-composer able to compile TypeScript, JSX files, and userscripts including dependencies.\n\nSure, we need some refactoring to enhance developer experience of userscript-composer project but here is the brief summary of the process.\n\n1. `cac` process cli part\n2. `esbuild` bundles and transforms userscripts\n3. `picomatch` recognizes glob patterns and exports to regular expression\n4. `terser` compresses the output\n\nIt's the basic thought I did first time to build this application.\nI think this would be helpful if you want to contribute.\n\nThen go to development section to continue.\n\n# Usage\n\n## Commands\n\nBefore getting started, let's create some folders and files for userscript-composer to work with.\nEvery options are changable, so don't worry.\n\n- **/scripts**; directory userscripts located\n- **/out**; directory output located\n- **/header.txt**; file prepended to unified userscript\n\nAlso, there are some terms used in this project:\n\n- **Unified userscript**, merged userscript including all subsequent userscripts under **/scripts** folder.\n- **Standalone userscript**, the standalone version of each userscripts under **/scripts** folder. (Or the term **bundled** maybe familiar to you)\n\n**Trivials**\n\n- Nothing now.\n\n**Shared options**\n\nThe options below are shared in all commands.\n\n```\nOptions:\n  --source [directory]  Set source directory to build (default: scripts)\n  --out [directory]     Set output directory for build (default: dist)\n  --minify              Minify the output for production use (default: false)\n  --clean               Clean the build directory before build (default: false)\n  -v, --version         Display version number\n  -h, --help            Display this message\n```\n\n### `userscript-composer init`\n\nCreate new userscript-composer workspace with `header.txt` template, `config.json` file, and script directory.\nThis command runs `userscript-composer build` automatically after setting up.\n\nIf you give some arguments for `build` command, it will automatically apply it.\n\n```bash\nuserscript-composer init [--source [directory]] [--out [directory]] [--minify] [--clean]\n```\n\n### `userscript-composer build`\n\nGenerate standalone userscript from source file.\n\n- Define source file via `--source [file]`.\n- Define out file via `--out [file]`.\n\n```bash\nuserscript-composer build [--source [file]] [--out [file]] [--minify] [--clean]\n```\n\n### `userscript-composer batch`\n\nBatch build userscripts from source directory and save bundled userscripts to output directory.\nGenerate standalone userscripts from source directory files including `.user.`.\n\n```bash\nuserscript-composer batch [--source [directory]] [--out [directory]] [--minify] [--clean]\n```\n\n### `userscript-composer unify`\n\nGenerate unified userscript bundling all userscripts from source directory.\n\n- Define header file location via `--header [filename]`.\n- Define the output file name via `--name [name]`.\n\n```bash\nuserscript-composer unify [--source [directory]] [--out [directory]] [--name [name]] [--header [headerfile]] [--minify] [--clean]\n```\n\n## API\n\nWe provide the JavaScript API to build from Node.JS application via ES Module format.\nRead more about [ES Module by Lin Clark](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/).\n\nBy seeing the [`/src/index.ts`](/src/index.ts), you can see what things are being exported via module.\nAlso, every functions necessary required to implement the build action has comment.\n\n# Development\n\nTo make our development environment to be flatten, here are the list of **necessary** softwares we should use.\nAs you know, the editor is not important and you may use any of released or your own.\n\n- Node.JS LTS Gallium (v16) as JavaScript Runtime\n- PNPM as Package Manager\n- All version manager supporting `.nvmrc`\n\nThat's all.\n\n\u003e WIP\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseia-soto%2Fuserscript-composer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseia-soto%2Fuserscript-composer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseia-soto%2Fuserscript-composer/lists"}