unjs
🌬️ siroc
sirocis a zero-config but extensible framework for developing Node applications and libraries
Features
- 💯 Zero-config required: Intelligent support for your package
- Supports running and compiling TypeScript and the latest JavaScript syntax
- ⚒️ Extensible: Write your own commands and build hooks
- 💪 Typescript: Fully typed and self-documenting
siroc is still a work in progress. Feedback is welcome, and changes will be frequent.
Quick start
Just install siroc.
# You can install siroc as a development dependency
yarn add siroc --dev
# ... or install globally
yarn global add sirocConfiguration
You can configure siroc by creating a siroc.config.ts, siroc.config.js or siroc.config.json file at the same level as your package.json.
In a monorepo, any configuration options at the root level are inherited by your workspaces, though of course you can override them.
import { defineSirocConfig } from 'siroc'
export default defineSirocConfig({
// fully typed options
})Commands
siroc build
siroc knows what to build based on your package.json.
By default, siroc will build your src/index.js or src/index.ts file into whatever output file is specified in your package.json's main field.
If you have specified additional binaries, siroc will look for input files matching their names.
Under the hood, siroc uses rollup and esbuild to build and produce type definitions for your files.
Monorepos
If you have enabled yarn workspaces, siroc will build each of your workspaces. You can choose to build only some of these by specifying what to build.
yarn siroc build @mypackage/cliWatch mode
You can build in watch mode, which will rebuild as necessary when source files change:
yarn siroc build --watchConfiguration
At the most basic level, your entrypoints are configured in your package.json:
bin(see npm docs)main,moduleandbrowser(see npm docs)typesif you want a TS declaration file to be generated for your main/module/browser entrypointsexports(see npm docs)
There are some conventions in place of configuration that are worth noting:
- the file type is inferred from the file name if possible (e.g.
babel.es.jswill be in 'es' format) maindefaults to CJS,moduleto ES,browserto UMD, andbinto CJS- if you have a folder mapped using subpath patterns and it matches a folder within your
srcfolder, the files within will be copied across and lightly transpiled using mkdist.
Example
{
"exports": {
".": {
// This will be compiled in CJS and matched to src/index.ts
"require": "./dist/index.js",
// This will be compiled in ES and matched to src/index.ts
"import": "./dist/index.es.js"
},
// src/templates will be lightly transpiled with mkdist and copied to dist/templates
"./templates/*": "./dist/templates/*",
// siroc will not touch this
"./package.json": "./package.json"
},
// This will be compiled in CJS and matched to src/index.ts
"main": "./dist/index.js",
// This will be compiled in ES and matched to src/index.ts
"module": "./dist/index.es.js",
// Types will be generated for src/index.ts
"types": "./dist/index.d.ts",
"bin": {
// This will be compiled in CJS and matched to src/cli/index.ts
"siroc": "bin/cli.js",
// This will be compiled in CJS and matched to src/cli/runtime.ts
"siroc-runner": "bin/runtime.js"
}
}Build hooks
siroc makes available three hooks for customising your build, if you need it.
build:extendbuild:extendRollupbuild:done
siroc dev
If you're working in a monorepo, it can be helpful to have accurate and up-to-date intellisense when importing from other libraries in a monorepo, without having to rebuild every time you make changes.
Running siroc dev will replace your package entrypoints with stubs that point to your source files. Your binaries will run your source files directly using jiti.
siroc run
You can run arbitrary shell commands or node scripts using the power of the jiti runtime.
For example:
# You can run a node script written in TypeScript
yarn siroc run myfile.ts
# You can run a command in all your workspaces
yarn siroc run ls --workspacesContributors
Contributions are very welcome.
Clone this repo
git clone https://github.com/unjs/sirocInstall dependencies and build project
yarn # Stub modules for rapid development yarn siroc dev # Test (on changes) yarn siroc jest
Tip: You can also run yarn link within a package directory to test the module locally with another project.
License
MIT License - Made with 💖