npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ahvn

v0.4.0

Published

Markdown driven task runner.

Downloads

2

Readme

ahvn

NPM version NPM downloads CircleCI donate chat

Markdown driven task runner.

Table of Contents

Install

You can install Maid globally:

# For npm users
npm i -g ahvn
# For Yarn users
yarn global add ahvn

Or if you want to ensure that your teammates are using the same version as you, it's recommended to install Maid locally:

# For npm users
npm i -D ahvn
# For Yarn users
yarn add ahvn --dev

PRO TIP: you can use npx or yarn command to run any locally installed executable that is inside node_modules/.bin/, e.g. use yarn ahvn to run the locally installed ahvn command.

What is a maidfile?

A maidfile is where you define tasks, in Markdown!

📝 maidfile.md:

## lint

It uses ESLint to ensure code quality.

```bash
eslint --fix
```

## build

Build our main app

<!-- Following line is a ahvn command for running task -->

Run task `build:demo` after this

```bash
# note that you can directly call binaries inside node_modules/.bin
# just like how `npm scripts` works
babel src -d lib
```

## build:demo

You can use JavaScript to write to task script too!

```js
const webpack = require('webpack')

// Async task should return a Promise
module.exports = () =>
  new Promise((resolve, reject) => {
    const compiler = webpack(require('./webpack.config'))
    compiler.run((err, stats) => {
      if (err) return reject(err)
      console.log(stats.toString('minimal'))
      resolve()
    })
  })
```

Each task is defined using h2 header and its child contents, the value of h2 header will be used as task name, its following paragraphs (optional) will be used as task description, and following code block (optional) will be used as task script.

Currently the code block languages are sh bash js javascript and more!.

Now run ahvn help to display the help for this maidfile:

❯ ahvn help

  lint        It uses ESLint to ensure code quality.
  build       Build our main app
  build:demo  You can use JavaScript to write to task script too!

❯ ahvn help "build*"

  build       Build our main app
  build:demo  You can use JavaScript to write to task script too!

To run a task, you can directly run ahvn <task_name>

❯ ahvn build
[13:46:38] Starting 'build'...
🎉  Successfully compiled 3 files with Babel.
[13:46:38] Finished 'build' after 363 ms...
[13:46:38] Starting 'build:demo'...
webpack compiled in 734ms.
[13:46:38] Finished 'build:demo' after 734 ms...

# to get minimal logs
❯ ahvn build --quiet
🎉  Successfully compiled 3 files with Babel.
webpack compiled in 734ms.

Run tasks before/after a task

You can run tasks before or after a task:

## build

Run task `deploy` after this

```bash
webpack --config config/webpack.config.js
```

## deploy

```bash
gh-pages -d dist
```

Expressions that start with Run(s)? task(s)? are treated specially. In this case if you run ahvn build it will also run the deploy task after build has finished.

The syntax is simple: Runs? tasks? <taskNames> (before|after) this (in parallel)? where each task name is surrounded by a pair of backticks: `.

By default a task will run before the current task. So Run task `build` would run build before the task it was described in. The presence of after anywhere in the sentence (after Run task) will cause it to be ran after. Commands run synchronously by default. The presence of in parallel in the sentence will cause it to be run in parallel.

Examples:

  • Run task `build`.
  • Run task `build` after this.
  • Run tasks `clean`, `build`, and `lint`.
  • Run tasks `build:app` `start:server` before this.
  • Run tasks `build:server` `build:client` before this in parallel.

Task hooks

Like npm scripts, when you run a command called build, when it's finished we will also run postbuild task.

Hook syntax:

  • pre<taskName>: Run before a specific task.
  • post<taskName>: Run after a specific task.
  • afterAll: Run after all tasks.
  • beforeAll: Run before all tasks.

Advanced

Code block languages

bash/sh

Read command line arguments

The CLI arguments are passed to executed script, so you can access it like this:

## log

```bash
echo $1
```

Then run ahvn log nice and it will print nice in the console.

js/javascript

The JS script will also be evaluated.

## log

```js
console.log(process.argv)
```
Asynchronous task

For asynchonous tasks, you can export a function which returns Promise:

## build

```js
module.exports = async () => {
  const files = await readFiles('./')
  await buildFiles(files)
}
```

py/python

## log

```py
print("cool")
```

Use a custom maidfile

By default, Maid would use maidfile.md, CONTRIBUTING.md or README.md (case-insensitive) in current working directory, when you're using README.md you need to manually specify the section of the markdown you wanna use as Maid tasks like below:

## My Project

## How to use

Let me explain..

## Development

<!-- maid-tasks -->

### test

```bash
# some test scripts...
```

Unlike a maidfile.md which uses all h2 headers as tasks, in README.md only h3 headers under the specified h2 header will be used as tasks. You can add a <!-- maid-tasks --> comment right below the desired h2 header.

Alternatively, if you're not using maidfile.md, you can also use --section h2_header and --path foo.md flags to customize it.

ZSH completion

Add FPATH like following to .zshrc:

export FPATH=$(npm root -g)/maid/completion/zsh:$FPATH

Development

Maid's own development scripts are powered by itself, run maid help or node bin/cli help in this project to get more.

lint

Run ESLint to ensure code quality and code style (via Prettier).

yarn eslint . "${@:1}"

If you want to automatically fix lint errors, try adding --fix plugin to the command you run, e.g. maid lint --fix

test

Use AVA to run unit tests.

yarn ava "${@:1}"

Similar to the lint task, you can append any flags for ava command directly when you run the maid command.

toc

Generate a table of contents section in the README.md file.

yarn doctoc README.md

Contributing

  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request :D

Author

maid © egoist, Released under the MIT License. Authored and maintained by egoist with help from contributors (list).

github.com/egoist · GitHub @egoist · Twitter @_egoistlily