symbiote (@-xun/symbiote)

Formerly xscripts (@-xun/scripts)

Symbiote is a highly-opinionated personal tool that supercharges 🕷️ all my NPM-based projects. It can also exist symbiotically within foreign repositories (e.g. when I'm contributing to open source), glomming onto clones and granting me some semblance of the powers I'm used to in my own projects. All without requiring changes to any of the foreign repository's files.

Symbiote is similar in intent to kcd-scripts, react-scripts, etc, but with many more opinions.

Motivation

I have three main goals with symbiote:

I. Concentrate the configuration explosion inherent in the modern JS ecosystem into one centralized location. That's symbiote. Reuse as much configuration from symbiote as possible. Spend as little time as possible tweaking configuration in repositories outside of symbiote. No more ugly package.json files filled with unreadable spaghetti scripts. Never have to worry about cross-environment concerns—symbiote works on both Linux and Windows.

Make it easy and quick integrate shiny new tooling into symbiote as the JS ecosystem changes. And when that same tooling falls out of fashion or is superseded, make it painless to augment, upgrade, or discard that same tooling, or replace it with an entirely different tool, across all projects using symbiote.

Projects that have tight integrations with tooling that ends up changing incompatibly or getting replaced have the option to pin the version of symbiote they require while other projects can continue to evolve as symbiote and the JS ecosystem does.

II. Minimize to near zero the context switching penalty I incur when shifting focus between projects. Especially open source. Keep coding fun after coding for work. Prevent burnout. Never be discouraged from returning to a very old project. Make each dev environment some level of predictable and familiar.

III. Standardize my opinion of an ideal toolchain, build process, and release flow. Reduce the complexity of managing CI/CD pipelines (i.e. GitHub Actions + xrelease) across a constellation of projects, and centralize the remaining complexity into xpipeline.

Make it super simple and unintimidating for others to contribute to symbiote-powered projects. Contributions can be made without the contributor ever knowing symbiote is there. "Continuous linting" tools like Husky, and npm scripts with standard names like "test" and "build", invoke symbiote when necessary. Symbiote encapsulates and hides the sprawling complexity of the JS ecosystem behind a stable-but-highly-opinionated API and CLI.

• Install
• Usage
• Appendix
  • Published Package Details
  • License
• Contributing and Support
  • Contributors

Install

You can install this package globally:

npm install --global @-xun/symbiote

And then execute the CLI:

npx symbiote ...

Alternatively, you can use npx to execute the CLI without pre-installation:

npx @-xun/symbiote ...

Usage

TODO

Appendix

Further documentation can be found under docs/.

Published Package Details

This is a CJS2 package with statically-analyzable exports built by Babel for use in Node.js versions that are not end-of-life. For TypeScript users, this package supports both "Node10" and "Node16" module resolution strategies.

That means both CJS2 (via require(...)) and ESM (via import { ... } from ... or await import(...)) source will load this package from the same entry points when using Node. This has several benefits, the foremost being: less code shipped/smaller package size, avoiding dual package hazard entirely, distributables are not packed/bundled/uglified, a drastically less complex build process, and CJS consumers aren't shafted.

Each entry point (i.e. ENTRY) in package.json's exports[ENTRY] object includes one or more export conditions. These entries may or may not include: an exports[ENTRY].types condition pointing to a type declaration file for TypeScript and IDEs, a exports[ENTRY].module condition pointing to (usually ESM) source for Webpack/Rollup, a exports[ENTRY].node and/or exports[ENTRY].default condition pointing to (usually CJS2) source for Node.js require/import and for browsers and other environments, and other conditions not enumerated here. Check the package.json file to see which export conditions are supported.

Note that, regardless of the { "type": "..." } specified in package.json, any JavaScript files written in ESM syntax (including distributables) will always have the .mjs extension. Note also that package.json may include the sideEffects key, which is almost always false for optimal tree shaking where appropriate.

License

See LICENSE.

Contributing and Support

New issues and pull requests are always welcome and greatly appreciated! 🤩 Just as well, you can star 🌟 this project to let me know you found it useful! ✊🏿 Or buy me a beer, I'd appreciate it. Thank you!

See CONTRIBUTING.md and SUPPORT.md for more information.

Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!