Table of contents
- Getting Started
- Running a tool
- Code of conduct (CoC)
- About SumUp
Foundry needs to be installed as a dev-dependency via the Yarn or npm package managers. The npm CLI ships with Node. You can read how to install the Yarn CLI in their documentation. Foundry requires Node v10.13+.
Depending on your preference, run one of the following.
# With Yarn$ yarn add --dev @sumup/foundry# With npm$ npm install --save-dev @sumup/foundry
Foundry exposes customizable configuration presets for the CLI tools it supports. To make use of these presets, you need to initialize a configuration file for each tool you would like to use. This is done with the
# With Yarn$ yarn run foundry init# With npm$ npx foundry init
Foundry will launch an interactive prompt to ask you questions about your project, such as in which language it is written, which frameworks it uses, or whether you are planning to open source it. Once you have answered all questions, Foundry will write the config files (don't worry, it asks before overwriting existing files) and will add scripts to your
package.json file to conveniently run the tools.
Alternatively, you can pass your answers to the
init command directly as flags. This is useful for environments such as CI where interactive prompts cannot be used. Here is an overview of all available options (you can view this help menu by running
npx foundry init --help):
A preset includes the configurations and scripts that are needed for a certain task.
Check code for syntax errors and format it automatically. The preset adds the following scripts to your
lint: check files for problematic patterns and report them
lint:fix: same as
lint, but also try to fix the issues
lint:ci: same as
lint, but also save the report to a file
The preset includes the following tools:
Eslint's configuration options:
|frameworks||array||'React', 'Emotion', 'Jest', 'Cypress'|||
Prettier is our code formatter of choice. It makes all our code look the same after every save.
Prettier currently has no configuration options.
lint-staged is a tool for running linters on files staged for your next commit in git. Together with Husky (see below) it prevents bad code from being committed.
lint-staged's configuration options:
Husky makes setting up git hooks very easy. Whenever someone installs your project, Husky will automatically set up git hooks as part of its
Husky currently has no configuration options.
Automatically generate release notes and (optionally) publish to NPM. The preset adds the following script to your
release: release and publish a new version
The preset includes the following tools:
semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.
semantic-releases's configuration options:
🤖 Continous Integration (CI)
Validate the code on every push using the 🔍 linting preset (if configured). The supported CI providers are:
- GitHub Actions builds, tests, and deploys your code right from GitHub.
Generate boilerplate code e.g. for React components. The preset adds the following script to your
create:component: generate the files for a React component
The preset includes the following tool:
Plop generates common files from templates. This is very helpful when creating similar files repeatedly and reduces the boilerplate you have to write as a developer.
Plop's configuration options:
|templateDir||string||A path relative to the location of plopfile.js||'.'|
⭐ This is an advanced use case.
Plop uses Handlebar templates to generate the files. If you'd like to override a built-in template, you can specify a custom template directory (see config options above). Plop will first check if a custom template exists, otherwise, it will fallback to the default template.
To see which variables are available for use in a Handlebars template, have a look at the default templates.
Running a tool
Foundry manages all supported tools for you and exposes them via the
run command. As an example: to run ESLint through Foundry execute:
# With Yarn$ yarn run foundry run eslint src# With npm$ npx foundry run eslint src
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.
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.
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. ✨
- Easy onboarding. New colleagues will be able to get productive much more quickly. 🙇♂️
- The number of direct dependencies becomes much smaller and your
But what makes Foundry different?
- 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.
Code of Conduct (CoC)
We want to foster an inclusive and friendly community around our Open Source efforts. Like all SumUp Open Source projects, this project follows the Contributor Covenant Code of Conduct. Please, read it and follow it.
If you feel another member of the community violated our CoC or you are experiencing problems participating in our community because of another individual's behavior, please get in touch with our maintainers. We will enforce the CoC.