Hammer your code into shape
About
Build tools that require a lot of explicit/declarative instructions are distracting. Anvil is a build system with an extension-based architecture that prefers convention over configuration. There are a lot of great ways to add new features or change almost any behavior as needed.
This Site
This site is a group effort to document the features and some of the extensions to Anvil. The source to the site itself is hosted here. If you so desire, you can submit pull requests to add documentation for your extensions or for things about the system you'd like to see covered.
Basic Features
All parts of the build process are implemented as extensions (specifically as build plugins). Some extensions ship along with anvil's source so that it can do _something_ out of the box. Most of the interesting features will likely be extensions that you install.
A baseline install can do the following:
- Install, remove, enable or disable extensions
- Automatically install any extensions your build file defines as dependencies
- Run local extensions (an extension that's not installed from npm)
- Continuously and incrementally build the project as files change
- Host static resources in an HTTP server
- Auto-refresh pages in the browser during CI mode
- Provides APIs to extensions for customized behavior
- Start and manage external processes
- Combine resource files through a comment-based import syntax
- Concat resource files in specified order using
- JSON or YAML file that lists files to create from other files
- individual JSON or YAML files
- Replace tokens (with customizable syntax) in source with
- values from package.json
- JSON or YAML key/value files
- Add file headers to final build output based on output file type
- Create default build files based on installed extensions
Frequently Asked Questions
Q. How is this different from Grunt?
A. Vastly, they are very different approaches to building projects.
Let us count the ways:
Imperative vs. Declarative
- Grunt takes a more imperative approach; required JS based build files
- Anvil takes a declarative approach; optional JSON build files
Convention over Configuration
- Grunt provides no top-level conventions but unlimited flexibility; tasks can happen in *any* order
- Anvil has a predefined asynchronous build workflow; plugins identify what activities they belong to
- Grunt requires a bit of setup per project and a build file in order to start using installed
- Once Anvil is installed, it will attempt to build projects even if there is no build file.
Extensions
- Grunt requires tasks to be installed locally per projects
- Anvil's extensions are installed globally with optional local overrides
- Grunt provides tasks as the primary way to define a build
- Anvil provides 4 types of extensions: plugins, commands, tasks and scaffolds
Another way to think about it is; Grunt can technically do anything but requires more effort to get common things done. Anvil's conventions and concepts satisfy a lot of common use cases with little effort and also provide several ways to extend the system.
Q. How is this different from Yeoman?
A. Yeoman is far more opinionated.
Yeoman and Anvil are similar in that they pull together many excellent open source libraries in order to help you with your project workflow. Yeoman is different in that it is very opinionated and has been built to use specific libraries for specific features; the end result is a very polished user experience but it comes at the expense of tight coupling to dependencies. Anvil has been designed to be so flexible that you can easily replace any behavior or feature with your own extension using a different set of open source libraries and get exactly the behavior you want. Feel like something's missing? You can add entirely new features and abilities (or even new types of extensions) to Anvil.
Q. Why does Anvil install globally?
A. Convenience, simplicity, speed.
Less setup effort on a per project basis means less time fiddling with a build system and more time spent on your project. Most of Anvil's extensions that aren't considered "core" to the build are opt-in or non-intrusive so you don't have to worry about a globally installed extension ruining your day. An additional advantage of a global plugins is that Anvil can manage keeping them up-to-date with one simple console command: anvil update. No need to worry about updating individual extensions on a per project basis.
Contributors
Special thanks to the following individuals who have contributed source code or ideas to help make anvil less buggy and more useful:
Legal Bits
"Anvil.js"( also referred to as "Anvil") is owned by Alex Robson. All rights not explicitly granted in the MIT or GPL license are reserved. See the included LICENSE-* files for more details.
Extensions to Anvil (plugins, commands, tasks, etc.) are not part of Anvil itself, and are the sole property of their respective maintainers. While every effort is made to ensure accountability, there is absolutely no guarantee, warrantee, or assertion made as to the quality, fitness for a specific purpose, or lack of malice in any given extension. Extensions published on the npm registry are not affiliated with or endorsed by myself (Alex Robson) or my employer unless otherwise stated in the repository for the extension.
If you have a complaint about an extension, and cannot resolve it with the package owner, please express your concerns to anviljs@gmail.com.
In plain english
This is mine; not my employer's. They have graciously supported the efforts and made contributions but are in no way responsible or liable for it's suitability or function.
If you create and publish an extension, it's yours, and you are solely accountable for it. Not me, not my employer.
If other people create and publish an extension, it's theirs. Not mine, not my employer's.
Malicious extensions could be published; consider the author behind the extension and perhaps review the code. There is no vetting process for published extensions.
If this concerns you, inspect the source before installing or using any extension.