🧰 futil

A library containing a few useful frontend utilities or futil for short 🙃 (@futil/core)

⚠️ WARNING: This library is a work in progress. Every release is at risk of having breaking changes, until its first major release.

Getting Started

Installation

The easiest way to get started is to install @futil/core:

# pnpm
$ pnpm add @futil/core

# yarn
$ yarn add @futil/core

# npm
$ npm i @futil/core --save

Or install individual futil packages

$ pnpm add @futil/v1
# When you install an individual package be sure to add peer dependencies yourself
$ pnpm add @futil/internal

How do you know which peer dependencies to install?

After installing the package, let's say @futil/v1, read the output of the install command or feel free to check the package.json of the package you installed by going into node_modules/@futil/v1/package.json.

Why would you install individual packages?

Possibility 1: Version Pinning.
If you want to lock your project into a certain version of @futil/v1, but keep everything else from @futil/core up to date, you can pin @futil/v1 to a certain version. For example, here's how you'd go about doing that:

$ pnpm add @futil/core@latest && pnpm add @futil/v1@0.0.2

// then your package.json will look like:

{ "dependencies": { "@futil/v1": "0.0.2", "@futil/core": "latest" } }

Possibility 2: Unnecessary Modules.
You just don't care for the rest of futil and only want a single package's utilities.

Usage

There are a few ways to import utilities from futil. Below are a few different approaches:

// Option 1 (Recommended): import module from individual package through `core`
import { getQueryParams } from '@futil/core/v1';
// Option 2 (Recommended): import module from individual package
import { getQueryParams } from '@futil/v1';
// Option 3 (NOT Recommended): import module from core
import { getQueryParams } from '@futil/core';

// then use the module however you please
const [filterParam, sortParam] = getQueryParams(['filter', 'sort']);

So what is futil?

This library was inspired by frontend engineers, trying to help other frontend engineers. This library was created to provide our fellow frontend engineers:

1. with utilities ranging from basic to advanced (as needed)
2. the ability to use just 1 utility - or many - without incurring nasty library bloat

Why not just use something like lodash or lodash.get?

While Lodash is an amazing library, it provides different kinds of helpers. Lodash simply serves a different purpose. Futil doesn't offer common JS utilities that help to shorten and optimize code. Futil provides frontend utilities that don't really exist in an existing popular library.

More on "Why futil?"

We are a small group of frontend engineers that have worked on large-scale projects, in high-growth startups or enterprise orgs... and have just repeatedly created the same utilities for each team.

Essentially, we just got tired of doing it over and over... and over.

Development

Scripts

# install dependencies
$ pnpm setup

# run tests
$ pnpm test

# or run tests in watch mode
$ pnpm test:watch

# create new package from plop template
$ pnpm plop:pkg

Contributing and Development

• Contribution Guide