There is a familiar little discomfort that shows up the first time a Node.js service needs to read something off disk that is not source code. An email template. A JSON schema. A seed fixture. A vendored PDF. The first version is always a one-liner: fs.readFile(path.join(__dirname, '../templates/welcome.ejs')). That works on your laptop. It also works in CI. And then you ship to production, your bundler flattens the output, __dirname points at dist/handlers/ instead of src/handlers/, the relative climb misses the templates directory, and the first user who triggers a password reset gets a 500.
The pragmatic fix is to scatter process.env.NODE_ENV === 'production' ? '../../dist/templates' : '../templates' across the codebase. The principled fix is to admit that on-disk assets are a build-time concern that deserves its own little type system. That is what the KickJS Asset Manager is.
The shape of the problem
Server-side asset resolution has three properties that conspire against you.
First, the path differs between dev and dist. Dev runs against src/, dist runs against a built output that may have a different layout, possibly minified, possibly bundled, possibly emitted by a different tool than the one that compiled your handlers.
Second, the keys are stringly-typed. readFile('templates/welcome.ejs') is just a string. Rename the file, forget to update the call site, and TypeScript gives you nothing — you find out at runtime, usually from a Sentry alert, usually from an end user.
Third, the cleanup story is bad. NODE_ENV checks, try/catch fallbacks, conditional __dirname math, helper functions that paper over the asymmetry — every codebase with on-disk assets accretes a small graveyard of these. They are correct individually and incoherent collectively.
The Asset Manager replaces all three problems with a single mental model: at build time, every asset you care about is copied into a known location and recorded in a manifest. At runtime, you address those assets through a typed proxy whose shape is generated from the manifest. There is no NODE_ENV, no __dirname arithmetic, and no string keys that the compiler cannot check.
The mental model: a manifest plus a typed proxy
Two artifacts do the heavy lifting.
The first is .kickjs-assets.json, a manifest emitted into dist/ during build. It is the canonical answer to "where, on this filesystem, is the asset named mails.welcome?". It is a flat JSON object — categories at the top level, slugs underneath, absolute or dist-relative paths as values.
The second is .kickjs/types/assets.d.ts, a generated declaration file that augments the framework-supplied KickAssets interface. The interface mirrors the manifest's shape exactly: KickAssets['mails']['welcome'] exists if and only if the manifest has an entry for mails.welcome. That augmentation is what gives the proxy its types.
The runtime side is a Proxy (or several flavours of one — see below). When you write assets.mails.welcome(), the proxy walks the path ['mails', 'welcome'], looks the slug up in the manifest, and returns the resolved file path. No filesystem reads, no environment checks, no path.join math in your handlers.
The result is that asset resolution becomes a pure function from a typed key to a string path, and every typo is a compile error.
The four ways to consume an asset
KickJS gives you four consumption patterns. They all resolve through the same manifest — the difference is purely ergonomic.
1. The ambient nested proxy
The default and most common pattern. Import once, address anywhere.
import { assets } from '@forinda/kickjs';
const path = assets.mails.welcome();
const html = await renderEjs(await readFile(path, 'utf8'), { user });
assets is a deeply-nested proxy whose shape comes from the augmented KickAssets interface. IDE autocomplete works at every level: assets. shows categories, assets.mails. shows slugs.
2. useAssets() — the hook factory
Sometimes you want the resolver as a value, not a singleton. useAssets() returns the same proxy but as a factory call, which is convenient when you want to swap implementations in tests or pass the resolver through a DI container.
import { useAssets } from '@forinda/kickjs';
class MailService {
constructor(private readonly assets = useAssets()) {}
welcome() { return this.assets.mails.welcome(); }
}
This is the form to reach for when you would otherwise be tempted to mock the import.
3. @Asset() — the class field decorator
For class-based services where you want the resolution to be lazy and declarative.
import { Asset } from '@forinda/kickjs';
class MailService {
@Asset('mails/welcome') private welcomeTpl!: string;
async send(user: User) {
const html = await renderEjs(await readFile(this.welcomeTpl, 'utf8'), { user });
}
}
The decorator installs a getter that resolves on first access. The string argument is type-checked against the manifest, so @Asset('mails/does-not-exist') is a compile error.
4. resolveAsset() — the dynamic escape hatch
When the key really is dynamic — an admin choosing a template at runtime, a feature-flagged variant — fall back to the function form.
import { resolveAsset } from '@forinda/kickjs';
const path = resolveAsset('mails', slug); // slug: string
You lose the per-key compile-time check, but the category is still typed and a missing slug throws a meaningful runtime error rather than returning a bogus path.
Build → manifest → runtime
The split between build and runtime is what makes the whole thing tractable.
kick build (or the focused kick build:assets) reads assetMap from kick.config.ts. Each entry has a src path (required), an optional dest (defaults to the entry's name), and an optional glob (defaults to **/*). For every entry, the builder walks the glob, copies matching files to dist/<dest>/, and records each one in .kickjs-assets.json. After the copy, kick typegen regenerates .kickjs/types/assets.d.ts so the type system reflects what was actually emitted.
// kick.config.ts
export default defineConfig({
assetMap: {
mails: { src: 'src/templates/mails', glob: '**/*.ejs' },
schemas: { src: 'src/schemas', glob: '**/*.json' },
fixtures:{ src: 'src/fixtures', dest: 'fixtures' }
}
});
At runtime, resolution follows a strict order. First, the manager checks KICK_ASSETS_ROOT — if set, that directory is treated as the asset root and every lookup is rooted there. Second, it tries to load .kickjs-assets.json from dist/ (or wherever the manager was initialized). Third — and only when running from source with no manifest present — it synthesizes a manifest by walking src/ according to assetMap, so that pnpm dev works without a build step.
The contract is straightforward: in production you have a manifest and the proxy is essentially a hash lookup; in dev you have a synthesized one and the proxy is essentially a filesystem walk plus a cache. Same API, same types, different machinery.
Type safety via typegen
kick typegen is the piece that closes the loop. It reads the manifest and writes a single .d.ts that augments the KickAssets interface declared by @forinda/kickjs:
declare module '@forinda/kickjs' {
interface KickAssets {
mails: { welcome: AssetRef; 'password-reset': AssetRef };
schemas: { user: AssetRef };
}
}
Once that file is on disk, assets.mails.does_not_exist() is a compile error, not a runtime exception. Filenames that are not valid identifiers — anything with a hyphen, a leading digit, a dot — are still safely addressable through bracket notation: assets.mails['password-reset'](). The generated interface uses string-literal keys for everything, so the bracket form keeps full autocomplete.
Run kick typegen (or let kick build do it for you) after any change to assetMap or to the files those entries point at. CI should treat a stale .kickjs/types/assets.d.ts as a failure.
Testing — fixture swapping
Because every lookup goes through the manifest, you can override the entire asset root at the process level by setting KICK_ASSETS_ROOT before the manager is first touched. Combined with clearAssetCache() to reset the manager between tests, this gives you a clean way to swap in fixtures without mocking.
beforeEach(() => {
process.env.KICK_ASSETS_ROOT = path.join(__dirname, 'fixtures');
clearAssetCache();
});
In a unit test for MailService, you can point at a fixtures/mails/welcome.ejs containing <h1>Hello {{name}}</h1> and assert on the rendered output without touching the real templates. The same trick works for snapshot fixtures, JSON-schema variants, anything where you want a known-good input.
When to reach for it
The Asset Manager is the right tool whenever the runtime answer is fs.readFile. Email templates rendered with EJS, Handlebars, or MJML. JSON schemas loaded by Ajv. Seed fixtures. PDFs and CSVs that ship with the app. Anything that lives on disk in dev, needs to live on disk in dist, and is consumed by your own server-side code.
It is not the right tool for HTTP-served static assets. Public images, downloadable user-facing files, anything a browser fetches — those want a static-file adapter or a CDN, not the Asset Manager. The line is "who reads this file?". If the answer is your handlers, use the manager. If the answer is a browser, use a serving layer.
The payoff for the in-scope cases is that you stop writing path math, you stop scattering environment checks, and you find typos at compile time instead of at 2 a.m. Once the manifest exists, the type system does the rest.