A simple, light-weight and modern task runner for general purpose.
<a href="https://github.com/shelljs/shelljs" target="_blank">shelljs </a>-like commands
yarn add -D foy # or npm i -D foy
Or install globally with
yarn add -g foy # or npm i -g foy
You need to add a Foyfile.js(or Foyfile.ts with tsx or @swc-node/register or ts-node installed) to your project root.
Also, you can simply generate a Foyfile.js via:
foy --init
which will create a simple Foyfile.js in the current folder:
// Foyfile.js
const { task } = require('foy')
task('build', async ctx => {
await ctx.exec('tsc')
})
You can also generate a Foyfile.ts via
foy --init ts
Then we can run foy build to execute the build task.
foy build
You can also add some options and a description to your tasks:
import { task, desc, option, strict } from 'foy'
desc('Build ts files with tsc')
option('-w, --watch', 'watch file changes')
strict() // This will throw an error if you passed some options that doesn't defined via `option()`
task('build', async ctx => {
await ctx.exec(`tsc ${ctx.options.watch ? '-w' : ''}`)
})
And, if using TypeScript, add types to your options through the task generic:
import { task, desc, option, strict } from 'foy'
type BuildOptions = {
watch: boolean
}
desc('Build ts files with tsc')
option('-w, --watch', 'watch file changes')
strict() // This will throw an error if you passed some options that doesn't defined via `option()`
task<BuildOptions>('build', async ctx => { // ctx.options now has type BuildOptions instead of unknown
await ctx.exec(`tsc ${ctx.options.watch ? '-w' : ''}`)
})
foy build -w
Warning! If you want to set flags like strict for all tasks, please use setGlobalOptions:
import { setGlobalOptions } from 'foy'
setGlobalOptions({ strict: true }) // all tasks' options will be strict.
option('-aa') // strict via default
task('dev', async ctx => {
})
option('-bb') // strict via default
task('build', async ctx => {
})
import { fs, task } from 'foy'
task('some task', async ctx => {
await fs.rmrf('/some/dir/or/file') // Remove directory or file
await fs.copy('/src', '/dist') // Copy folder or file
let json = await fs.readJson('./xx.json')
await ctx
.env('NODE_ENV', 'production')
.env('NODE_ENV=production')
.cd('./src')
.exec('some command') // Execute an command
let { stdout } = await ctx.exec('ls', { stdio: 'pipe' }) // Get the stdout, default is empty because it's redirected to current process via `stdio: 'inherit'`.
})
import { task, logger } from 'foy'
import * as axios from 'axios'
task('build', async ctx => {
let res = await axios.get('https://your.server/data.json')
logger.info(res.data)
})
import { task } from 'foy'
import * as axios from 'axios'
task('test', async ctx => {
await ctx.exec('mocha')
})
task('build', async ctx => {
let res = await axios.get('https://your.server/data.json')
console.log(res.data)
await ctx.exec('build my awesome project')
})
task(
'publish:patch',
['test', 'build'], // Run test and build before publish
async ctx => {
await ctx.exec('npm version patch')
await ctx.exec('npm publish')
}
)
Dependencies run serially by default but you can specify when a task should be run concurrently.
Example: Passing running options to dependencies:
task(
'publish:patch',
[{
name: 'test',
async: true, // run test parallelly
force: true, // force rerun test whether it has been executed before or not.
}, {
name: 'build',
async: true,
force: true,
},],
async ctx => {
await ctx.exec('npm version patch')
await ctx.exec('npm publish')
}
)
/* Sugar version */
task(
'publish:patch',
[ 'test'.async().force(),
'build'.async().force() ],
async ctx => {
await ctx.exec('npm version patch')
await ctx.exec('npm publish')
}
)
/*
Priority for async tasks
Default is 0, higher values will be run earlier; so, in this next example, `build` will be run before `test`.
(Note: If you have multiple async dependencies with same priority, they will be executed in parallel.)
*/
task(
'publish:patch',
[ 'test'.async(0).force(),
'build'.async(1).force() ],
async ctx => {
await ctx.exec('npm version patch')
await ctx.exec('npm publish')
}
)
You can also pass options to dependencies:
task('task1', async ctx => {
console.log(ctx.options) // "{ forceRebuild: true, lazyOptions: 1 }"
console.log(ctx.global.options) // options from command line "{ a: 1 }"
})
task('task2', [{
name: 'task1',
options: {
forceRebuild: true,
},
// Some options that rely on ctx or asynchronization,
// it will be merged to options.
resolveOptions: async ctx => {
return { lazyOptions: 1 }
}
}])
// foy task2 -a 1
To avoid name collisions, Foy provides namespaces to group tasks via the namespace function:
import { task, namespace } from 'foy'
namespace('client', ns => {
before(() => {
logger.info('before')
})
after(() => {
logger.info('after')
})
onerror(() => {
logger.info('onerror')
})
task('start', async ctx => { /* ... */ }) // client:start
task('build', async ctx => { /* ... */ }) // client:build
task('watch', async ctx => { /* ... */ }) // client:watch
namespace('proj1', ns => { // nested namespace
onerror(() => {
logger.info('onerror', ns)
})
task('start', async ctx => { /* ... */ }) // client:proj1:start
})
})
namespace('server', ns => {
task('build', async ctx => { /* ... */ }) // server:build
task('start', async ctx => { /* ... */ }) // server:start
task('watch', async ctx => { /* ... */ }) // server:watch
})
task('start', ['client:start'.async(), 'server:start'.async()]) // start
// foy start
// foy client:build
Foy wraps the NodeJS's fs (file system) module with a promise-based API, so you can easily use async/await patterns, if you prefer. Foy also implements some useful utility functions for build scripts not present in NodeJS's built-in modules.
import { fs } from 'foy'
task('build', async ctx => {
let f = await fs.readFileSync('./assets/someFile')
// copy file or directory
await fs.copy('./fromPath', './toPath')
// watch a directory
await fs.watchDir('./src', (event, filename) => {
logger.info(event, filename)
})
// make directory with parent directories
await fs.mkdirp('./some/directory/with/parents/not/exists')
// write file will auto create missing parent directories
await fs.outputFile('./some/file/with/parents/not/exists', 'file data')
// write json file will auto create missing parent directories
await fs.outputJson('./some/file/with/parents/not/exists', {text: 'json data'})
let file = await fs.readJson('./some/jsonFile')
// iterate directory tree
await fs.iter('./src', async (path, stat) => {
if (stat.isDirectory()) {
logger.info('directory:', path)
// skip scan node_modules
if (path.endsWith('node_modules')) {
return true
}
} else if (stat.isFile()) {
logger.warn('file:', path)
}
})
})
Foy includes a light-weight built-in logger
import { logger } from 'foy'
task('build', async ctx => {
logger.debug('debug', { aa: 1})
logger.info('info')
logger.warn('warn')
logger.error('error')
})
A simple wrapper for sindresorhus's lovely module execa
import { logger } from 'foy'
task('build', async ctx => {
await ctx.exec('tsc')
// run multiple commands synchronously
await ctx.exec([
'tsc --outDir ./lib',
'tsc --module es6 --outDir ./es',
])
// run multiple commands concurrently
await Promise.all([
ctx.exec('eslint'),
ctx.exec('tsc'),
ctx.exec('typedoc'),
])
// restart process when file changes
ctx.monitor('./src', 'node ./dist')
ctx.monitor('./src', ['rm -rf dist', 'tsc', 'node dist'])
ctx.monitor('./src', async () => {
await ctx.run('build:server')
await ctx.exec('node ./dist') // auth detect long-running process when using ctx.exec
})
ctx.monitor('./src', async (p) => {
// manually point out the process need to be killed when restart
p.current = require('child_process').exec('node dist')
})
})
If you use Foy in CI servers, you won't want the loading spinners as most CI servers will log stdout and stderr in discreet frames not meant for continuous streaming animations. Luckily, Foy has already considered this! You can simply disable the loading animation like this:
import { task, setGlobalOptions } from 'foy'
setGlobalOptions({ loading: false }) // disable loading animations
task('test', async cyx => { /* ... */ })
/*
$ foy test
DependencyGraph for task [test]:
─ test
Task: test
...
*/
You can add lifecycle hooks via the before, after, and onerror functions.
import { before, after, onerror } from 'foy'
before(() => { // do something before all tasks tree start
// ...
})
after(() => { // do something after all tasks tree finished
// ...
})
onerror((err) => { // do something when error happens
// ...
})
task('task1', async ctx => { /* ... */ })
task('task2', async ctx => {
// do things before task1
// run task1 manually, so we can
// do things before or after it
await ctx.run('task1')
// do things after task1
})
task('build', async ctx => { /* build your project */ })
let p = null
task('watch', async ctx => {
ctx.monitor('./src', async ()=> {
ctx.exec('node ./src/server.ts')
})
})
# Write Foyfile in ts, enabled by default
foy -r ts-node/register -c ./some/Foyfile.ts build
# Write Foyfile in coffee
foy -r coffeescript/register -c ./some/Foyfile.coffee build
Add foy auto completion in zsh/bash:
# for bash
foy --completion-profile >> ~/.bashrc
# for zsh
foy --completion-profile >> ~/.zshrc
https://zaaack.github.io/foy/api
MIT
FAQs
A simple, light-weight and modern task runner for general purpose.
We found that foy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.