Create-fp-ts-lib NPM

create-fp-ts-lib

Bootstrap libraries that follow common fp-ts coding, documentation and testing patterns.

Introduction
Getting started
- Yarn
- NPM
Features
Recipes
CLI Options
Future features

Introduction

fp-ts brings typed functional programming to TypeScript. The advantage over functional languages that compile to JavaScript is that it's much closer to an already existing and typed ecosystem.

This provides a nice out of the box compatibility. However, fp-ts is most powerful and composable if special purpose libraries follow some conventions. The fp-ts ecosystem is still relatively small. create-fp-ts-lib helps you to bootstrap libraries that follow common fp-ts coding, documentation and testing patterns.

This is the main goal of this project. However it may be useful to create any other TypeScript library as well. Currently nothing inherently fp-ts specific is generated, except from a peer dependency. But this may change in the future.

Getting started

Yarn

yarn global add create-fp-ts-lib
create-fp-ts-lib

If you want don't want to go through the questions, you can run create-fp-ts-lib -q -n my-lib to just specify a name and use the defaults for any other options.

You can also use this shortcut to always invoke an up to date version:

yarn create fp-ts-lib

NPM

npm install -g create-fp-ts-lib
create-fp-ts-lib

If you want don't want to go through the questions, you can run create-fp-ts-lib -q -n my-lib to just specify a name and use the defaults for any other options.

You can also use this shortcut to always invoke an up to date version:

npm init fp-ts-lib

Features

Code Quality

Code formatting by prettier
Linting with ESLint

Testing

Test framework: ts-jest
Property based testing using fast-check

Documentation

API generation by docs-ts
JSDoc formatting using prettier-plugin-jsdoc
README post-processing with markdown-magic (e.g. table of content generation)
Code spell checking by cspell

Building

tsconfig.json settings that emits distributable .d.ts and .js files

Continuos Integration

CI via GitHub Actions
Generate docs and deploy to GitHub pages using github-pages-deploy-action
Easy publishing to NPM by drafting a release on GitHub

Dev tasks

All task scripts postfixed with :watch run as vscode tasks
Note: You need to Ctrl+shift+P and Tasks: Manage Automatic Tasks in Folder and choose "Allow Automatic Tasks in folder"

Recipes

Commands

Command	Action
`yarn build`	Build distribution files
`yarn test`	Run test suite
`yarn docs`	Generate Documentation
`yarn lint`	Run linter
`yarn md`	Enhance README with auto generations
`yarn spell`	Run the code spell checker

You can use npm as well. Check the generated package.json for available watch tasks.

Serve docs on GitHub pages

Push to your remote repo at GitHub (triggers CI)
In the GitHub UI of your repo, go to "Settings" > "GitHub Pages"
Select gh-pages branch as source, keep the "root" directory and "Save"

Publish to NPM

Only once:
- In the GitHub UI add NPM_TOKEN from you NPM account as a secret ("Settings" / "Secrets")
On every release:
- Increase the version in the package.json e.g. to "1.0.1"
- Commit as v1.0.1
- In the GitHub UI, go to the "releases" section of your repo.
- Select "Create a new release"
- Use v1.0.1 as "Tag version" and "Release title"
- Click "Publish release"
- Check the "Actions" tab to see if CI runs properly

Update existing repository

Currently the tool is optimized for creating new projects from scratch. However, we provide an --inPlace option, which is not very smart yet. It will just generate files as usual and possibly override existing files. You'll need to sort out changes manually. The CLI will make sure your git working directory is clean.

CLI Options

Run create-fp-ts-lib --help to see all options.

Note: Unless you provide the --noQuest flag, every CLI option will still appear in the user questionnaire. However equipped with the provided CLI options as default answers.