Type-Safe Asset Management for Node.js with KickJS Asset Manager

Node.js developers often face silent failures when their applications attempt to read non-code assets like templates or configuration files in production. A common pattern starts with a simple one-liner—fs.readFile(path.join(__dirname, '../templates/welcome.ejs'))—which works perfectly in development but breaks after bundling or minification. The KickJS Asset Manager addresses this issue by introducing a build-time manifest and runtime type safety, eliminating environment-specific path hacks and reducing runtime errors.

Why on-disk asset resolution is error-prone

Server-side asset resolution introduces three persistent challenges that degrade reliability and maintainability.

• Path discrepancies between environments: In development, assets reside in src/, but after building, they may be located in dist/ with a completely different directory structure. Hardcoded paths fail because the working directory changes.

• Lack of type safety: Asset paths are treated as strings. Renaming a file or directory breaks the application, but TypeScript cannot detect this at compile time, leading to runtime failures often reported by users or monitoring tools.

• Accumulation of workaround code: Codebases often accumulate conditional logic, helper functions, and environment checks to handle asset resolution. While each workaround may be correct in isolation, collectively they create technical debt and increase the risk of subtle bugs.

A structured solution: manifest plus typed proxy

The KickJS Asset Manager replaces ad-hoc workarounds with a two-phase system—build time and runtime—that ensures consistency and type safety.

Build-time manifest generation

During the build process, the manager compiles a manifest file—.kickjs-assets.json—into the dist/ directory. This manifest maps logical asset names to their resolved file paths. For example, an asset named mails.welcome might resolve to /dist/templates/mails/welcome.ejs. The manifest is generated from a configuration in kick.config.ts, where developers define src, dest, and optional glob patterns for asset inclusion.

// kick.config.ts
assetMap: [
  { src: 'src/templates/mails/', glob: '**/*.ejs' }
]

The build command kick build:assets processes this configuration, copies matching files into the dist/ directory, and records each file’s path in the manifest. This ensures assets are physically present and locatable in production.

Runtime type-safe resolution

At runtime, a type-safe proxy reads the manifest and resolves asset paths based on logical keys. The proxy is generated from the manifest and exported as a deeply nested object or function, with its shape reflected in a typed interface—KickAssets.

For instance, accessing assets.mails.welcome returns the correct file path, and any typo—like assets.mails.welcom—results in a compile-time TypeScript error, preventing deployment of invalid references.

Four practical ways to use assets

KickJS supports multiple patterns for accessing assets, each optimized for different use cases.

1. Nested proxy access (default)

Import a single proxy and use it across the application. This approach combines simplicity with type safety and IDE support.

import { assets } from '@forinda/kickjs';

const path = assets.mails.welcome();
const html = await renderEjs(await readFile(path, 'utf8'), { user });

The proxy’s shape mirrors the manifest, so autocomplete guides developers through available categories and asset slugs.

2. Factory function for dependency injection

When you need to swap asset resolution logic—such as in tests or when using dependency injection—use the factory function useAssets().

import { useAssets } from '@forinda/kickjs';

class MailService {
  constructor(private readonly assets = useAssets()) {}

  async sendWelcome(user: User) {
    const path = this.assets.mails.welcome();
    const html = await renderEjs(await readFile(path, 'utf8'), { user });
    // ... send email
  }
}

This pattern supports mocking and swapping implementations without modifying class constructors.

3. Class field decorator for lazy resolution

For class-based services, use the @Asset() decorator to resolve asset paths lazily when the class field is first accessed.

import { Asset } from '@forinda/kickjs';

class MailService {
  @Asset('mails/welcome')
  private welcomeTpl!: string;

  async sendWelcome(user: User) {
    const html = await renderEjs(await readFile(this.welcomeTpl, 'utf8'), { user });
  }
}

The decorator validates the asset key against the manifest at compile time. Invalid keys trigger TypeScript errors immediately.

4. Dynamic resolution with runtime validation

When asset keys are determined dynamically—such as when users select templates via admin interfaces—use resolveAsset() to handle runtime validation.

import { resolveAsset } from '@forinda/kickjs';

const path = resolveAsset('mails', dynamicSlug);

This function validates the category name at runtime and throws a clear error if the asset does not exist, avoiding silent failures from incorrect paths.

Build once, resolve everywhere

The KickJS Asset Manager decouples asset resolution from environment-specific concerns by treating it as a build-time task. This shift enables developers to write cleaner, more maintainable code without sacrificing reliability.

By generating a manifest and typed proxy at build time, the system ensures that every asset reference is verifiable at compile time and resolvable in production. This eliminates the need for conditional logic, reduces technical debt, and improves the developer experience across the entire lifecycle of a Node.js application.

As applications scale and asset inventories grow, tools like KickJS Asset Manager become essential for maintaining consistency and reducing operational overhead. Integrating such systems early in development can prevent costly refactoring and debugging cycles down the line.