One tool. The whole frontend.
imp is a complete UI toolkit in one binary. It is the dev server, the component library, the state, the router, the test runner, the linter, the formatter and the bundler. You install one file, and you build the app. You assemble nothing, and you connect nothing.
Experimental. imp is in an early phase and has no stable release yet. Some things can work in a way that is not intended. Every API, config key and command can change. Use it at your own risk.
curl -fsSL https://imp-ui.com/install.sh | bashirm https://imp-ui.com/install.ps1 | iexx64 and arm64. Then run imp init my-app.
How imp works
No build step
The browser runs the file that you typed
There is no compile step, no JSX and no virtual DOM. A component is a plain function that returns a real DOM node.
- One binary holds the dev server, the test runner, the linter, the formatter and the dependency manager.
- A unit test runs in process, with no browser. An end-to-end test runs in a real headless Chrome, and a spec records itself as a GIF.
- Production is the one place where a build exists. It emits plain static files.
imp start # serve the source that you typed
imp test --unit # every *.test.js, in process
imp test --e2e # every *.spec.js, in a real browser
imp lint --fix # one rule set, with autofixes
imp fmt # one formatterState
State lives in the parent component
A component initializes a named state. Every component under it reads the same state by name.
- There is no store to configure, no provider to wrap and no re-render.
- A change updates only the DOM that you bound to it.
- The state lives as long as its component stays mounted.
Components
A component is a web component
The name that you choose is the HTML tag. The component renders into its own shadow root.
- The setup runs after the browser connects the element, so the state of a parent is already there.
- You call a component like any element factory, and you pass it the same kinds of arguments.
import { component } from 'imp'
import { button, div, span } from 'imp/html'
import { initState } from 'imp/state'
export const counter = component('app-counter', {
setup: (self) => {
const count = initState(self, 'app.count', 0)
return div(
span(count.text()),
button('+1', { events: { click: () => count.set((n) => n + 1) } }),
)
},
})Styling
The styles stay inside the component
A styles key holds the CSS of the component. The shadow root keeps it there, and nothing leaks out.
- Every colour, length and font reads an --imp-* token. A theme change reaches your component with no code.
- Logical properties make the component correct in both text directions.
export const panel = component('app-panel', {
styles: `
:host { display: block }
.panel {
padding: var(--imp-space-4, 16px);
border: var(--imp-border-width, 1px) solid var(--imp-color-border, #cbd5e1);
border-radius: var(--imp-radius-container, 10px);
background: var(--imp-color-surface, #ffffff);
}
`,
setup: (_self, ...children) => div({ class: 'panel' }, ...children),
})Dev server
A dev server that an agent can read
The browser console, every error and every request stream to your terminal.
- The whole session lands in a plain text log. imp logs -f follows it.
- The review widget sits on every page. Click an element, describe what is wrong, and imp writes a text file with the page and the element.
- Your agent reads the reviews with imp review, so it does not guess what you meant.
imp logs -f
imp logs | grep '[browser:error]'
imp reviewStandard library
A rich standard component library
Forms, tables, overlays, navigation, charts, icons and the app frame ship inside imp.
- Every component is themed, translated, accessible, and tested in both text directions.
- Icons are built in, and you pay only for the ones that you draw.
- A real app ships with zero external dependencies.
import { button, comboBox, dialog, icon, table, tabs } from 'imp/std'
import { luSearch } from 'imp/icons'
button({ variant: 'primary', events: { click: search } }, icon(luSearch), 'Search')The app map
The whole app on one screen
One file names every screen, its path and its purpose. The router binds a component to each node.
- imp map prints the tree, so a person and an agent read the same plan.
- A node with no screen yet renders a placeholder, so the plan runs before the code exists.
import { appMap } from 'imp'
export const app = appMap({
todos: { $id: 'One todo, on its own page' },
about: 'Who made this, and why',
})Mocks
A backend that does not exist yet
Point imp.json at a folder of *.mock.js files. The dev server answers the requests itself.
- The app runs before the first endpoint exists.
- The end-to-end tests run against the same mocks.
- One flag switches the same app to the real API.
export const mocks = [
{
match: (request) => request.method === 'GET' && request.path === '/api/users',
delay: 800,
handler: () => [{ id: 1, name: 'Ada' }, { id: 2, name: 'Grace' }],
},
]CLI
One command line for the whole loop
Every step of a project is a subcommand of imp. There is nothing to connect.
- Scaffold, serve, test, lint, format, preview, review, build, install and update come from one binary.
- imp update pins the version of imp in the project, so every clone runs the same imp.
imp init my-app # a real app, and it runs
imp start # serve it, with mocks
imp preview # every component, in isolation
imp test --unit # unit tests
imp test --e2e # end-to-end tests
imp lint # check the code
imp fmt # format the code
imp build # static files, for any CDN
imp install marked # vendor a dependencyimp skill
The manual, written for your agent
imp skill prints a manual out of the binary, at the exact version that the project runs.
- It works offline, and it makes no network call.
- The index costs one call. A subject costs one more.
- Your own components ship a skill file next to them, and the same command prints it.
imp skill # the index
imp skill state routing # two manuals in one call
imp skill std/button # a standard component
imp skill ./components/counter.jsAnalytics
See which parts of the UI work
imp helps you build the UI, and also measure how well it works for your users. It counts the pages, the zones and the outcomes of your app.
- Every page view is recorded, with no code per route.
- A zone counts how often any part of a screen is seen and used, with no code in the component.
- imp comes with its own analytics server, imp-aly. Run it on your own VPS. Google Analytics, PostHog or your own endpoint also work.
- A record carries no personal data, and imp stores no id on the device.
import { onAnalytics, track, zone } from 'imp/analytics'
import { alySink } from 'imp/analytics/aly'
onAnalytics(alySink({
app: 'myapp',
servers: ['https://aly.myapp.example'],
}))
zone({ name: 'myapp.due-date' }, dueDatePicker())
track('myapp.invoice-sent')Ship
Build once, host anywhere
imp build writes plain static files into dist/. Upload the folder as it is.
- There is no runtime, no import map and no server to run.
- What you tested in development is what you ship.
- A pwa block in imp.json makes an installable app that works offline.
imp build
imp build --env prodThe workflow with imp
- 1
Define the app map
Name every screen, its path and its purpose in one file. imp map prints the tree, so the plan is visible before the first component exists.
imp map - 2
Ask your agent to generate the app
Point the agent at imp skill. It reads the manual of what it is about to write, at the version that the project runs, and it builds the screens from the map.
imp skill - 3
Review the design against mocked clients
Ask for mocked HTTP clients, so the whole app runs with no backend. Click through it. Leave a note on any element with the review widget, and hand the notes to the agent.
imp start --mock - 4
Build the backend when the frontend is approved
The stakeholders sign off on an app that they can click. Then the backend implements the contract that the mocks describe, and imp build ships the frontend to a CDN.
imp build
Iterate from whichever step you want. A new screen starts at the map. A design change starts at the review. A changed contract starts at the mocks.
Why imp
Your idea is the best app ever, in your head
Build it as soon as you can, and validate it on the market.
Do not spend the first weeks on tools and on how to connect them.
imp is the whole frontend in one binary. Ship the idea, then learn from the people who use it.
FrontendBackendApp
imp is a boring project, on purpose
It aims to be the correct fit for most applications, and good enough where it is not perfect.
It does not chase the smallest bundle, and nobody tuned it to win a benchmark. A boring tool is a tool that you stop thinking about.
imp solves the frontend half of the app, and it stays out of the other half.
The SPA is the best thing that happened to the IT industry
A single-page application, or SPA, is a frontend that stands on its own. It asks the backend for data only.
Many companies push a render server into every app, and you pay them to render what a browser renders for nothing. The SPA is the way to go.
Build a page or a componentimp promotes it first, and it works in a server-rendered page too. Build a component as a JS entry, and the HTML that your server returns embeds it as an interactive island.
Nobody writes code by hand anymore
AI changes what "best practice" means.
Many tools of today cover a gap that JavaScript has since closed, and somebody designed them for code that a person types. When an agent writes the code and maintains it, those constraints no longer apply in the same way. So
imp returns to techniques that people once called bad practice, and uses them well.
Where the standard components end, the agent continues
imp does not try to ship every component. With the correct constraints, an agent generates the missing one.
A kanban board or a seat map is a component of yours. The agent writes it on the foundations of
How a component of yours fits inimp: the theme tokens, the state, the translations and the accessibility rules.
imp skillhands it those rules, so the result fits next to a standard component.The PWA is the app that installs from a URL
A Progressive Web App is a promising technology, and
imp supports it in full.
One build flag emits the manifest, the icon set and an offline service worker. The app installs to a home screen from a link, with no store and no second codebase. It is where the SPA position leads.
Build a PWA
Examples
The imp-examples project holds three complete apps that are built with imp. Two of them run live in the browser:
- Beacon is an observability SPA with a
shell, a router, guards, forms, charts and translations. The hosted build has no backend, so
sign-in fails there. Run it with
imp startto use its mock API. - Brickfall is a brick breaker game on a canvas. It installs as a PWA and plays offline.
The third app is a shop that a Deno server renders, with imp components as islands. It runs locally only.
Why the name imp
The first name was imperator, for imperative code. A modern framework is declarative, and in some
cases an imperative line is simpler than the declarative way. imp is a hybrid. It renders declaratively, and it lets you write
imperative code wherever that is the easier path.
An imp is the friendly familiar from a role-playing game, and that is what this project wants to be. It goes with you and your agent while you build the frontend.