🚧 Under construction 🚧

This project is still at an early stage. We are testing it internally and hope to add more powerful features as well as tools.

Foundry

An opinionated but configurable CLI (Command Line Interface) toolkit for writing JavaScript. We currently support React, Node, and vanilla JavaScript with varying feature breadth.

TLDR;

1. Set up desired configuration files, npx foundry bootstrap-config —eslint —prettier.

2. Add commands to package.json

   "scripts": {
       "lint": "foundry run eslint src"
   }
   

3. Be productive and don’t worry about tooling dependencies.

Table of contents

• Examples
• Installation
• Usage
• Commands
• Why?
• Contribute
• About SumUp

Installation

Foundry is supposed to be installed as a dev-dependency (development) via the npm or Yarn package managers. The npm CLI ships with Node. You can read how to install the Yarn CLI in their documentation.

Depending on your preference, run one of the following.

# With npm
$ npm install --save-dev @sumup/foundry

# With yarn
$ yarn add --dev @sumup/foundry

Usage

Once you have installed Foundry, you should bootstrap configuration files the CLI tools you would like to use through Foundry and set up scripts in you package.json to actually run them.

Bootstrap configuration files

Foundry exposes customizable configuration presets for the CLI tools it supports. To make use of these presets, you need to bootstrap a configuration file for each tool you would like to use. This is done with the bootstrap-config command. Foundry supports different presets for each tool, base being the default preset. You can specify the tool you would like to use as a flag, the preset as the flag’s value.

# Bootstraps the eslint and prettier config files using the react preset for ESLint and the default (base) preset for prettier.
$ npx foundry bootstrap-config --eslint react --prettier

Running a tool through Foundry

Foundry manages all supported CLI tools for you and exposes them via the run command. To run ESLint through Foundry execute npx foundry run eslint src from the terminal. Here, src is the folder you want ESLint to check. Note that you can use any of the command line flags and arguments supported by ESLint and other tools. Foundry simply forwards them and they get handled by the tool. For example, to have ESLint fix your linting errors, run npx foundry run eslint --fix src.

Use Foundry for your package.json scripts

For automation purposes and easier access, you will want to alias frequently used commands as scripts in your package.json. Here are some examples.

"scripts": {
    "lint": "foundry run eslint --fix src",
    "create-component": "foundry run plop component"
}

List of commands

At the moment, Foundry supports two commands; bootstrap-config and run. They allow you to create configurations and run the cooresponding tools. The tools we support are Babel, ESlint (with Prettier), Plop. We will add more documentation here. For now, you can try foundry --help or foundry {command} --help to se your options.

List of configuration presets

Here is a list of supported presets for the bootstrap-config command, grouped by CLI tool.

ESLint (--eslint flag)

We lint our code with ESLint. Linting our code helps us spot mistakes early. You can inspect all presets in the respective config file.

• base: the default preset. Uses the airbnb-base, prettier, and jest/recommended presets, prettier and jest plugins and some configurations.
• node: like base but specifies node as environment.
• react: like base but adding the react/recommended, jsx-a11y/recommended, and prettier/react presets.

Prettier (--prettier flag)

Prettier is our code formatter of choice. It makes all our code look the same after every save. We only have a base preset, which follows our default formatting rules.

Plop (—plop flag)

Plop allows us to quickly create a set of files, e.g. for a React component, with a single command. This is very helpful when creating a lot of components and reduces the boilerplate you have to write as a developer.

Currently, we only have a plop generator for React components. Use the react preset for that.

Why?

TLDR

Creating and maintaining a JavaScript project can be very tedious. There are tools, configurations, dependency management, and boilerplate. With Foundry, you can fix all of that with a single dependency. It lints, creates files, links configurations, and (soon) runs your build. And the best part? You can still get down and dirty with your configurations. But only if you want.

The problem

Setting up and maintaining a complex JavaScript project can be very tedious.There are many different dependencies to install (linters, testing frameworks, bundlers) and configurations to set up. Once you have a running project, you end up writing a lot of boilerplate code when creating commonly used files. For example, a React component might come with a spec file (test), a Storybook file (isolated component development), and a service for handling business logic.

It gets much, much worse when you have several (many?) projects. What happens, when there is a breaking change in a tooling dependency? What if team decides you need to add a new linting rule? Nobody wants to go through every project and update those files all the time. And who knows, if they are even the same? Syncing configurations is terrible. Or think about that new engineer you are onboarding. How are they supposed to know how you structure your project, how your components are supposed to look, which files they need to create?

You might think you could solve these issues with a boilerplate repository and some snippets or templates. But you cannot. At least the maintenance problem will not go away.

The solution

Toolkits are a way to mitigate these kinds of problems. They encapsulate as much as possible of the your toolchain into a single dependency and expose it through a CLI. Doing so gets you the following, probably more!

• You don't need to set up any tooling when creating a new project. Bootstrap it and start coding. 🚀
• When you need to update a tooling dependency or change a configuration, do it in the toolkit and update the toolkit dependency in your projects — preferably in an automated fashion. That's it. ✨
• Make the way you write JavaScript more consistent. All your projects will work exactly the same. 📏
• Easy onboarding. New colleagues will be able to get productive much more quickly. 🙇‍♂️
• The number of direct dependencies becomes much smaller and your package.json shorter. 🕸️

But what makes Foundry different?

We were inspired by many toolkit projects, such as create-react-app and kcd-scripts. These projects are opinionated, and so is Foundry. But Foundry is different, in our opinion, because:

• It encapsulates tools and their configurations, but also lets you get down and dirty with the configs in your project.
• It merely proxies the tools you use on a CLI level instead of talking to them through their Node.js APIs. We literally execute the binaries and forward any options you provided.

So please, go ahead and try it.

Contribute

We are currently not ready for contributions. If you have questions, feature requests, or want to report a new bug, please file an issue.

About SumUp

SumUp is a mobile-point of sale provider. It is our mission to make easy and fast card payments a reality across the entire world. You can pay with SumUp in more than 30 countries, already. Our engineers work in Berlin, Cologne, Sofia, and Sāo Paulo. They write code in JavaScript, Swift, Ruby, Elixir, Erlang, and much more. Want to come work and with us? Head to our careers page to find out more.