awilix-vite

2.0.3 verified Mon Apr 27 auth: no javascript

Awilix integration for Vite projects, version 2.0.3. Provides a `loadModules` function that bridges Awilix's module loading with Vite's `import.meta.glob` for automatic dependency registration. Unlike loadModules in awilix itself (which uses glob patterns and file system scanning), this plugin relies on Vite's static analysis for dynamic imports. Requires manual use of `import.meta.glob` and does not work with lazy glob patterns. Ships TypeScript types. Designed for client-side or SSR Vite setups.

Common errors

error Cannot find module 'awilix-vite' or its corresponding type declarations. ↓

cause Missing installation or incorrect import path.

fix

npm install awilix-vite and ensure import is from 'awilix-vite' (not 'awilix').

error TypeError: loadModules is not a function ↓

cause Default import used instead of named import.

fix

Use import { loadModules } from 'awilix-vite'.

error Error: loadModules expects a globResult from import.meta.glob, received undefined ↓

cause import.meta.glob used without eager: true, or the pattern didn't match any files.

fix

Add '{ eager: true }' and ensure glob pattern matches at least one file.

Warnings

breaking import.meta.glob with eager=true is required for loadModules to work. Without eager, loaded modules are lazy imports and may not register correctly. ↓

fix Use { eager: true } in import.meta.glob call.

gotcha loadModules uses Vite's static analysis; dynamic glob patterns (e.g., variable paths) are not supported. The pattern must be a string literal. ↓

fix Use a hardcoded glob pattern, not a variable.

deprecated Importing from 'awilix' (not '/browser') may cause runtime errors in browser environments due to Node dependencies (e.g., fs). ↓

fix Import createContainer and other Awilix primitives from 'awilix/browser'.

gotcha The formatName option receives the filename without extension; if your module files are named kebab-case, the default camelCase conversion may mangle names. ↓

fix Provide a formatName function that matches your naming convention.

Install

npm install awilix-vite

yarn add awilix-vite

pnpm add awilix-vite

Imports

loadModules

wrong

const loadModules = require('awilix-vite')

correct

import { loadModules } from 'awilix-vite'

ESM-only package; require() will fail. Use import.

loadModules

wrong

import loadModules from 'awilix-vite'

correct

import { loadModules } from 'awilix-vite'

This is a named export, not a default export.

loadModules
wrong
```
import { loadModules } from 'awilix'
```
correct
```
import { loadModules } from 'awilix-vite'
```
awilix core does not export loadModules in browser/ESM builds. Use this plugin instead.
createContainer
wrong
```
import { createContainer } from 'awilix'
```
correct
```
import { createContainer } from 'awilix/browser'
```
If using in browser/Vite, import from 'awilix/browser' to avoid Node-specific code.

Quickstart

Shows how to create an Awilix container, use import.meta.glob with eager=true, and load modules with lifecycle options.

import { createContainer } from 'awilix/browser';
import { loadModules } from 'awilix-vite';

const container = createContainer();

// Must use eager: true
const modules = import.meta.glob('./services/*.js', { eager: true });

loadModules(container, modules, {
  resolverOptions: {
    lifetime: 'SINGLETON'
  },
  formatName: (name) => name
});

export { container };