{"id":21423486,"url":"https://github.com/theonethread/falkor-bundler","last_synced_at":"2025-07-14T08:31:22.889Z","repository":{"id":37808421,"uuid":"378113460","full_name":"theonethread/falkor-bundler","owner":"theonethread","description":"Opinionated ES6 JavaScript / TypeScript module bundler","archived":false,"fork":false,"pushed_at":"2023-06-21T15:40:28.000Z","size":440,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-07-09T23:28:25.692Z","etag":null,"topics":["bin","binary","build-tool","bundler","cli","es6","falkor","lib","library","tool","typescript"],"latest_commit_sha":null,"homepage":"https://falkor.world","language":"JavaScript","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/theonethread.png","metadata":{"funding":{"ko_fi":"falkor_framework","custom":"https://www.linkedin.com/in/barnabas-bucsy"},"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-06-18T10:21:49.000Z","updated_at":"2024-04-20T04:02:26.000Z","dependencies_parsed_at":"2023-01-20T23:03:49.271Z","dependency_job_id":null,"html_url":"https://github.com/theonethread/falkor-bundler","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/theonethread/falkor-bundler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theonethread%2Ffalkor-bundler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theonethread%2Ffalkor-bundler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theonethread%2Ffalkor-bundler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theonethread%2Ffalkor-bundler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theonethread","download_url":"https://codeload.github.com/theonethread/falkor-bundler/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theonethread%2Ffalkor-bundler/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265262600,"owners_count":23736427,"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":["bin","binary","build-tool","bundler","cli","es6","falkor","lib","library","tool","typescript"],"created_at":"2024-11-22T21:16:31.434Z","updated_at":"2025-07-14T08:31:22.637Z","avatar_url":"https://github.com/theonethread.png","language":"JavaScript","funding_links":["https://ko-fi.com/falkor_framework","https://www.linkedin.com/in/barnabas-bucsy"],"categories":[],"sub_categories":[],"readme":"# **Falkor Bundler**\n\n[![Npm Keywords](https://img.shields.io/github/package-json/keywords/theonethread/falkor-bundler \"Keywords\")](https://www.npmjs.com/package/@falkor/falkor-bundler \"Visit\") \u0026nbsp; [![Npm Package](https://img.shields.io/npm/v/@falkor/falkor-bundler \"Npm\")](https://www.npmjs.com/package/@falkor/falkor-bundler \"Visit\") \u0026nbsp; [![Node Version](https://img.shields.io/node/v/@falkor/falkor-bundler \"Node\")](https://nodejs.org/ \"Visit\") \u0026nbsp; [![Build](https://img.shields.io/github/workflow/status/theonethread/falkor-bundler/Falkor%20CI%20-%20Release \"Build\")](https://github.com/theonethread/falkor-bundler/actions \"Visit\") \u0026nbsp; [![Security](https://img.shields.io/github/workflow/status/theonethread/falkor-bundler/Falkor%20CI%20-%20Security?label=security \"Security\")](https://github.com/theonethread/falkor-bundler/actions \"Visit\") \u0026nbsp; [![Activity](https://img.shields.io/github/last-commit/theonethread/falkor-bundler \"Activity\")](https://github.com/theonethread/falkor-bundler \"Visit\") \u0026nbsp; [![Rollup](https://img.shields.io/npm/dependency-version/@falkor/falkor-bundler/rollup \"Rollup\")](https://www.npmjs.com/package/rollup \"Visit\") \u0026nbsp; [![TypeScript](https://img.shields.io/npm/dependency-version/@falkor/falkor-bundler/typescript \"TypeScript\")](https://www.npmjs.com/package/typescript \"Visit\") \u0026nbsp; [![Snyk Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/github/theonethread/falkor-bundler \"Snyk\")](https://snyk.io/test/github/theonethread/falkor-bundler \"Visit\") \u0026nbsp; [![License](https://img.shields.io/npm/l/@falkor/falkor-bundler \"MIT\")](https://github.com/theonethread/falkor-bundler/blob/master/license.txt \"Visit\")\n\nThe `falkor-bundler` project is a standalone `npm` command-line application written in vanilla JavaScript to bundle ES6 Node.js JavaScript or TypeScript projects (mainly to be used with the **Falkor Framework**).\n\nThe project aims to abstract away distinct build setting difficulties from developers, requiring only to follow certain predefined rules, which are necessary for the automation of:\n\n- TypeScript compilation\n- Resolution of compile-time conditions\n- Module bundling - including tree-shaking\n- Plus:\n  - In `debug` mode:\n    - Sourcemaps for generated JavaScript, and declaration-maps pointing to local TS sources (for linked usage while developing)\n  - In `release` mode:\n    - Minification of resulting JavaScript bundle\n    - Creation of flattened declaration file (for consuming when used as a dependency)\n\n## **Installation**\n\n### **Development Dependency**\n\nInclude the `@falkor/falkor-bundler` in the `package.json` file under `devDependencies`:\n\n```\n...\n  \"devDependencies\": {\n    ...\n    \"@falkor/falkor-bundler\": \"1.2.3\"\n  }\n```\n\n_**NOTE:** And don't forget to run `npm install` afterwards._\n\n### **Command Line Interface**\n\nTo install the package locally with `npm` (this will alter your `package.json`):\n\n```\n$ npm install @falkor/falkor-bundler --save-dev\n```\n\nIt's also possible to install the package globally, so it's available in your `PATH`:\n\n```\n$ npm install @falkor/falkor-bundler --global\n```\n\n## **Usage**\n\n### **Development Dependency**\n\nAs a dependency, one can use the command-line executable in `npm` scripts. As part of `package.json` under `scripts` this will suffice:\n\n```\n  \"scripts\": {\n    ...\n    \"debug\": \"rimraf .dist/**/* \u0026\u0026 falkor-bundler --debug\",\n    \"release\": \"rimraf .dist/**/* \u0026\u0026 falkor-bundler\"\n  }\n```\n\n_**NOTE:** `falkor-bundler` creates a release bundle by default, and **will not** empty the output directory before. It was designed this way to support building multiple outputs (eg. both an exported module and a command line application), so a good starter for bundling is to use [`rimraf`](https://www.npmjs.com/package/rimraf \"Visit\") or similar, to do the cleanup of the exact output(s) of your distinct jobs yourself._\n\n### **Command Line Interface**\n\nUsage:\n\n```\nfalkor-bundler [--release | --debug] [--silent] [(--input \u003cfile\u003e)] [(--out \u003cdir\u003e)] [(--context \u003cctx\u003e)] [(-- \u003cexternals\u003e...)]\nfalkor-bundler [-r | -d] [-s] [(-i \u003cfile\u003e)] [(-o \u003cdir\u003e)] [(-c \u003cctx\u003e)] [(-- \u003cexternals\u003e...)]\nfalkor-bundler (-v | --version | -h | --help)\n```\n\nOptions:\n\n- `-v` or `--version`: Show version and exit\n- `-h` or `--help`: Show help and exit\n- `-r` or `--release`: Bundle in `release` mode, only used for readability (default)\n- `-d` or `--debug`: Bundle in `debug` mode\n- `-s` or `--silent`: Do not print messages\n- `-i \u003cfile\u003e` or `--input \u003cfile\u003e`: Entry `.ts` or `.js` file (default: `src/index.ts`)\n- `-o \u003cdir\u003e` or `--out \u003cdir\u003e`: Output directory of bundle (default: `.dist`)\n- `-c \u003cctx\u003e` or `--context \u003cctx\u003e`: [JSCC](https://github.com/aMarCruz/jscc \"Visit\") compilation context (see below)\n- `-- \u003cexternals\u003e...`: Treat all positional arguments after double dash as externals\n\nJSCC Context:\n\nA space delimited string that uses `#` prefix for variables when parsed. Eg. `\"#VALUE #KEY example\"` will extend the compilation context with `{ \"_VALUE\": true, \"_KEY\": \"example\" }` after parsed.\n\nIf for some reason the `#` character is reserved in your workflow, it can be substituted with any special character starting the value with the `\":\u003cspecial-char\u003e \"` sequence, eg. `\":$ $VALUE $KEY example\"`.\n\n_**NOTE:** `cwd` must be the project root, where `package.json` and `tsconfig.json` can be found. The `--input` file and `--out` directory will be resolved from here._\n\n## **Required Repository Structure**\n\nThe `falkor-bundler` project was mainly developed to compile ES6 `npm` packages in the **Falkor Framework** infrastructure, for that these repositories **must**:\n\n- Be valid ES modules written in strict TypeScript (or vanilla JavaScript)\n- Have `\"type\": \"module\"` entry in `package.json`\n- Have either a `\"module\"` or `\"bin\"` entry in `package.json`\n\n### **Required Library Structure**\n\nIf a module exposes a library, that must be its main purpose, and it must be indicated in `package.json`. This does not mean, that it can not have accompanying binaries, eg. tools, boilerplate generators, etc. For a library project `package.json` **must**:\n\n- Have `module` entry named after `main` entry's base name with `js` extension (default: `index.js`)\n- Have `typings` entry named after `main` and `module` entries' base names with `d.ts` extension (default: `index.d.ts`)\n\n\u003e While developing a library, best practice is to bundle it up locally in `debug` mode, and link this local package to your application with `npm`. Since in `debug` mode both sourcemaps and declaration-maps are present, one will get meaningful source code locations in errors, and your IDE will navigate seamless between the consuming application and the linked module's sources.\n\u003e\n\u003e _**SEE:** [`npm-link`](https://docs.npmjs.com/cli/v7/commands/npm-link \"Visit\") for further reference._\n\n### **Required Binary Structure**\n\nBinaries can be standalone Node.js applications, or accompanying tools for your exposed library. For binary projects `package.json` **must**:\n\n- Have a `bin` entry that is:\n  - Either a single string input location (in this case the binary will use your project's name from `package.json`)\n  - Or an object that's keys are the names of the binaries, and their values are the input locations\n\n\u003e _It is a good idea to package a `man` page with standalone applications. You can check out this project's setup in [`package.json`](https://github.com/theonethread/falkor-bundler/blob/master/package.json \"Open\") and [`man.md`](https://github.com/theonethread/falkor-bundler/blob/master/man/man.md \"Open\") for details._\n\n### **Required Shared Module Structure**\n\nIt is possible to internally share modules between binaries and your library, in this case the shared module will not get compiled into both your projects' artifacts, but it will have to be handled separately. For internally shared modules `package.json` **must**:\n\n- Have a `shared` entry that is:\n  - Either a single string input location\n  - Or an array of string input locations\n\n\u003e _It is advised not to over-complicate these setups, one should consider the whole dependency tree of all projects when doing so._\n\u003e\n\u003e _For a complex setup using this technique you can check out the `falkor-auth-server` project on [GitHub](https://github.com/theonethread/falkor-auth-server \"Visit\")._\n\n### **TypeScript Configuration**\n\nThe project needs a valid `tsconfig.json` in the root directory, but all compiler options will be overridden by the internal mechanism, so this file is merely used as linter settings by your IDE.\n\n## **Further Development**\n\nTo clone the repository and compile `falkor-bundler` one can use the commands:\n\n```\n$ git clone --branch develop git@github.com:theonethread/falkor-commander.git\n$ cd falkor-commander\n$ npm install\n$ npm run [ debug | release ]\n```\n\nThis will use the project's raw JavaScript source to create a distribution from itself. :sunglasses:\n\n\u003e _**SEE:** `\"scripts\"` entry in [`package.json`](https://github.com/theonethread/falkor-library/blob/master/package.json \"Open\") for further reference._\n\n### **Man Page**\n\nBy default the `falkor-bundler` module ships with a pre-compiled man page when installed on Unix-like operating systems. The manual was created by converting the file [`man/man.md`](https://github.com/theonethread/falkor-bundler/blob/master/man/man.md \"Open\").\n\nTo recompile the manual, make sure that [`Pandoc`](https://pandoc.org/ \"Visit\") is installed, and present in the `PATH`, then run:\n\n```\n$ npm run man\n```\n\n### **Linting**\n\nThe project uses [`prettier`](https://www.npmjs.com/package/prettier \"Visit\") for code formatting and [`cspell`](https://www.npmjs.com/package/cspell \"Visit\") to avoid general typos in both sources and documentation - it is advised to install these packages as extensions in your IDE to prevent CI errors beforehand. To lint the project run:\n\n```\n$ npm run lint\n```\n\n\u003e _**SEE:** [`.prettierrc.cjs`](https://github.com/theonethread/falkor-bundler/blob/develop/.prettierrc.cjs \"Open\") and [`cspell.config.cjs`](https://github.com/theonethread/falkor-bundler/blob/develop/cspell.config.cjs \"Open\") for further reference._\n\n- To fix formatting issues run `$ npx prettier --write \u003cpath-to-file\u003e`. This will overwrite the file with the default formatting applied locally, so then you can review the changes in `git` and **ensure those did not affect production artifacts**.\n- To fix spelling errors run `$ npx cspell lint --wordsOnly --unique --gitignore --exclude .git ** .*` for details, and either make the fixes in the sources listed, add `cspell` favored comments, or extend the project-wide `cspell.config.cjs` accordingly.\n\n### **Versioning and Branching Strategy**\n\nRelease sources can be found on the `master` branch, this one always points to the latest tagged release. Previous sources of releases can be found using `git` version tags (or browsing GitHub releases). Released packages can be found on [npmjs](https://www.npmjs.com/package/@falkor/falkor-bundler \"Visit\").\n\nThe repository's main branch is `develop` (due to technical reasons), this holds all developments that are already decided to be included in the next release. Usually this branch is ahead of `master` one patch version (but based on upcoming features to include this can become minor, or major), so prepared external links may yet be broken.\n\nThe `feature/*` branches usually hold ideas and POC code, these will only be merged into `develop` once their impact measured and quality meets release requirements.\n\n\u003e _The project uses [SemVer](https://semver.org \"Visit\"), `git` tags are prefixed with a `v` character._\n\n### **GitHub Actions**\n\nThe workflows can be found [here](https://github.com/theonethread/falkor-bundler/blob/develop/.github/workflows \"Open\").\n\n#### **Continuous Integration**\n\nAutomatic builds are achieved via GitHub actions, CI will make nightly builds of the `develop` branch (using Ubuntu image), and test `master` when there is a pull request, or commit on it (using Ubuntu - Win - MacOS image matrix).\n\n### **Security**\n\nThe project uses [CodeQL](https://codeql.github.com \"Visit\") and [Snyk](https://snyk.io \"Visit\") to ensure standard security.\n\n\u003e _The **Falkor Framework** supports a healthy and ubiquitous Internet Immune System enabled by security research, reporting, and disclosure. Check out our [Vulnerability Disclosure Policy](https://github.com/theonethread/falkor-bundler/security/policy \"Open\") - based on [disclose.io](https://disclose.io \"Visit\")'s best practices._\n\n### **Free and Open Source**\n\nThe latest sources can always be found on [GitHub](https://github.com/theonethread/falkor-bundler \"Visit\").\n\n#### **Getting Involved**\n\nWe believe - and we hope you do too - that learning how to code, how to think, and how to contribute to free- and open source software can empower the next generation of coders and creators. We **value** first time contributors just the same as rock stars of the OSS world, so if you're interested in getting involved, just head over to our [Contribution Guidelines](https://github.com/theonethread/.github/blob/master/.github/contributing.md \"Open\") for a quick heads-up!\n\n#### **License**\n\n[MIT](https://github.com/theonethread/falkor-bundler/blob/master/license.txt \"Open\")\n\n##\n\n---\n\n_©2020-2023 Barnabas Bucsy - All rights reserved._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheonethread%2Ffalkor-bundler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheonethread%2Ffalkor-bundler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheonethread%2Ffalkor-bundler/lists"}