imp - Build flags
A build flag turns part of your app on or off, per environment. The new checkout can be on in development and off in production, until the day you turn it on. imp decides the flag when it builds, not while the app runs, and that is what the name says. imp gives you one function for that, and a guarantee about what happens at build time.
import { flag } from 'imp'
if (flag('CHECKOUT_V2')) {
mountNewCheckout()
}
In development, imp reads the flag while the app runs. In production, imp does not read it at all.
imp build resolves every flag before it bundles, and folds the answer into the code. A flag
that is off takes its whole branch with it: the call, the branch, the functions only that branch
called, and any module only that branch imported. What ships is the app as if nobody had written the
disabled feature.
That is the difference between a flag and a piece of configuration. Configuration is a value your app reads. A flag is a decision you make before imp packages your app.
How to declare a flag
Declare every flag in imp.json, in a list of names:
{
"flags": ["CHECKOUT_V2", "NEW_NAV"],
"environments": {
"dev": "env/dev.json",
"prod": "env/prod.json"
}
}
A name you never declared is an error, not a flag that silently stays off. A spelling mistake such
as flag('CHEKOUT_V2') stops the build and lists the flags you did declare. It never hides a
feature you meant to ship. A flag name must not start with IMP_, which is reserved for the values
imp reads itself.
How to turn a flag on
The state of a flag per environment lives in the file for that environment, beside your other values. Configuration explains how imp selects an environment:
{
"API_URL": "https://api.example.com",
"CHECKOUT_V2": false
}
imp accepts only true and false. In a .env file, write the strings CHECKOUT_V2=true and
CHECKOUT_V2=false. Any other value stops the command. A declared flag that an environment does
not mention is off. So a file needs only the flags you turn on, and a new flag stays safely off
everywhere until you change it.
A declared flag is a flag, and nothing else. It is not part of the env object, and a read of
env.CHECKOUT_V2 never finds it. There is one way to read a flag: the way the build can fold.
Development, production, and what the browser sees
imp start and imp preview read a flag while the page runs. A change to a flag in an environment
file needs a reload, not a rebuild. A change of environment, with imp start --env prod, shows you
the app exactly as that environment has it.
imp build resolves the flags once, at the start. Every flag() call becomes the literal true or
false it evaluated to, and the minifier drops what is now unreachable. The finished output has no
flag machinery: no list of flag names, no values, nothing for a visitor to read or change. Each
build prints what it decided, so a release tells you which gates it shipped with:
built index.html -> dist/
flags folded in - CHECKOUT_V2 off, NEW_NAV on
How to write a flag the build can fold
Write the flag name as a literal string at the call:
flag('CHECKOUT_V2') // ok
flag(name) // fails - the build stops and tells you why
This is the one rule that makes the guarantee complete. imp can remove a branch only when it knows
at build time which branch that is. When you must look something up by a name you compute at
runtime, that is configuration, not a flag. Put it in an environment value and read it through
env.
Everything else is ordinary JavaScript. A flag reads well anywhere a boolean does:
import { flag } from 'imp'
import { div } from 'imp/html'
const nav = () => (flag('NEW_NAV') ? newNav() : classicNav())
export const page = () => div(nav(), flag('CHECKOUT_V2') && promoBanner())
To keep a large disabled feature, and any library only it uses, out of the bundle, put it behind a
dynamic import() inside the gate. When the flag is off, the branch disappears, and imp never emits
the chunk that import would produce:
if (flag('CHECKOUT_V2')) {
const { mountNewCheckout } = await import('./checkout/new.js')
mountNewCheckout()
}
Flags in tests
A test runs your modules directly, not through a production build. imp reads a flag at runtime, so a test can set the flags it wants to exercise:
import { flag } from 'imp'
import { afterEach, expect, test } from 'imp/test'
afterEach(() => {
delete globalThis.__IMP_FLAGS__
})
test('the new checkout is gated', () => {
globalThis.__IMP_FLAGS__ = { CHECKOUT_V2: true }
expect(flag('CHECKOUT_V2')).toEqual(true)
})
When a flag is the wrong tool
imp decides a flag when it builds. When the answer must change while the app runs, that is data your app loads, not a flag. Put it in your own state instead. Examples are an answer per signed-in user, an answer per A/B bucket, or an answer fetched from a service.
A flag is for a shipping decision: work in progress that is not ready, a feature one environment has before another, or a switch you turn off and deploy again.