create-fp-ts-lib

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

Table of Contents

• Introduction
• Getting started
  • Yarn
  • NPM
• Features
  • Code Quality
  • Testing
  • Documentation
  • Building
  • Continuos Integration
  • Dev tasks
• Recipes
  • Commands
  • Serve docs on GitHub pages
  • Publish to NPM
  • Update existing repository
• 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.

Future features

The following features are planned

• Check dependencies with depcheck
• Precommit hooks
• Run CI locally in isolated environment
• Readme badges (npm version, build status, dependencies)
• Watch task for linting using eslint-watch
• Maybe you have an idea... File an issue