assets-toolkit
v1.0.3
Published
Type-safe asset management CLI for React Native, Expo, React, Next.js and Vite. Automatically scans, validates and generates typed asset imports.
Maintainers
Readme
Assets Toolkit
Generate clean, typed, production-ready asset maps for React Native, Expo, React, Next.js, and Vite projects.
ssets Toolkit scans your project assets, validates them, detects duplicates and risky files, then generates a typed asset map you can import from your app code. It is built for teams that want asset access to feel boring in the best way: consistent names, stable imports, and fewer surprises during release.
It helps teams keep asset management predictable with:
- Consistent asset names
- Type-safe imports
- Duplicate detection
- Platform compatibility checks
- Cleaner release builds
assets/ generated-assets/
logo.png ─────▶ index.ts
icons/search.svg images-generate.ts
fonts/Inter.ttf svg-generate.ts
fonts-generate.ts✨ Why Use It?
- 🚀 Generate one typed
Assetsobject from images, SVGs, fonts, audio, video, and Lottie files. - 🗂️ Preserve nested asset folder structures.
- 🧹 Detect duplicate files before they increase app size.
- 🛡️ Catch invalid filenames before Metro, Vite, Next.js, or CI builds fail.
- 📊 Analyze asset usage and platform compatibility.
- ♻️ Clean generated files and cache whenever required.
📦 Installation
Install it as a development dependency:
npm install --save-dev assets-toolkitOr run it directly with npx:
npx assets-toolkit help⚡ Quick Start
Put assets in one of the default folders:
assets/
logo.png
icons/
search.svg
fonts/
Inter.ttfGenerate asset files:
npx assets-toolkit generateImport generated assets:
import { Assets } from "./generated-assets";
const logo = Assets.images.logo;
const searchIcon = Assets.svg.images.search;
const font = Assets.fonts.fonts.Inter;📁 Generated Location
Assets Toolkit automatically detects your project structure.
If your project contains a src folder:
src/
├── assets/
└── generated-assets/If your project does not contain a src folder:
assets/
generated-assets/You can always override this using:
{
"output": "custom/generated/path"
}🌐 Platform Support
Assets Toolkit automatically detects your project platform.
| Platform | Images | SVG | Fonts | Audio | Video | Lottie | | ------------ | ------ | --- | ----- | ----- | ----- | ------ | | React Native | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Expo | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | React | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Next.js | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Vite | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Unsupported formats are reported during generation.
🧭 CLI Commands
| Command | Purpose |
| ----------------- | --------------------------------- |
| generate, -g | Generate typed asset files |
| doctor | Validate assets and detect issues |
| doctor --fix | Fix invalid filenames |
| reports | Generate asset reports |
| clean, -c | Remove generated files |
| --version, -v | Show package version |
| help, -h | Show CLI help |
🚀 Generate
Generate asset maps:
npx assets-toolkit generateAlias:
npx assets-toolkit -gOptions:
npx assets-toolkit generate --outDir src/generated-assets
npx assets-toolkit generate --assetsDir assets
npx assets-toolkit generate --assetsDirs assets,src/shared/assetsThe generator creates:
generated-assets/
index.ts
images-generate.ts
svg-generate.ts
fonts-generate.ts
audio-generate.ts
video-generate.ts
lottie-generate.tsGenerated output:
export const Assets = {
images,
svg,
fonts,
audio,
video,
lottie,
} as const;🩺 Doctor
Check your asset setup:
npx assets-toolkit doctorChecks:
- Missing asset folders
- Invalid filenames
- Duplicate assets
- Unsupported formats
- Large files
🛠 Doctor Fix
Preview fixes:
npx assets-toolkit doctor --fixSkip the confirmation prompt when you want an automated cleanup:
npx assets-toolkit doctor --fix --yesThis command can:
- Rename invalid filenames into safe asset names.
- Avoid collisions with files that already exist.
- Remove duplicate asset files after confirmation.
📊 Reports
Generate an asset report:
npx assets-toolkit reportsIncludes:
- Asset counts
- Storage usage
- Largest files
- Extension breakdown
- Generated output information
clean
♻️ Remove generated files and the Assets Toolkit cache.
npx assets-toolkit cleanAlias:
npx assets-toolkit -cUse this when you want to regenerate from a clean state.
--version
🏷️ Print the installed package version.
npx assets-toolkit --version
npx assets-toolkit -vhelp
💡 Show CLI help.
npx assets-toolkit help
npx assets-toolkit -h⚙️ Configuration
On first run, Assets Toolkit creates:
assets-toolkit.config.jsonDefault:
{
"assets": ["./src/assets", "./assets"],
"output": "generated-assets",
"target": "auto",
"duplicates": "ignore"
}Config Options
| Option | Type | Description |
| ------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| assets | string[] | Asset directories to scan. |
| output | string | Directory where generated files are written. Must stay inside the project root. |
| target | string | Valid target value: auto, react-native, expo, react, next, vite, or unknown. The CLI auto-detects the active platform from package dependencies. |
| duplicates | string | Duplicate preference value: ignore, warn, or error. Duplicate files are surfaced by generate, doctor, and doctor --fix. |
🧩 Supported Assets
| Category | Extensions |
| -------- | ------------------------------------------------------------------ |
| Images | .png, .jpg, .jpeg, .gif, .webp, .avif, .heic, .ico |
| SVG | .svg |
| Fonts | .ttf, .otf, .woff, .woff2 |
| Audio | .mp3, .wav, .aac, .m4a, .ogg, .flac, .opus |
| Video | .mp4, .mov, .webm, .m4v |
| Lottie | .lottie, valid Lottie .json |
🌍 Web Asset Handling
For React, Next.js, and Vite projects, generated assets use native ESM asset resolution:
export const images = {
logo: new URL("../assets/images/logo.png", import.meta.url).href,
};This allows bundlers like:
- Webpack
- Turbopack
- Vite
to correctly resolve assets.
✅ Filename Rules
Recommended:
logo.png
logo-dark.svg
[email protected]
Inter.ttfAvoid:
my logo.png
bad!name.svg
LOGO.PNGClean filenames produce predictable generated keys.
🧪 Recommended Workflow
Add scripts:
{
"scripts": {
"assets": "assets-toolkit generate",
"assets:check": "assets-toolkit doctor",
"assets:fix": "assets-toolkit doctor --fix",
"assets:report": "assets-toolkit reports",
"assets:clean": "assets-toolkit clean"
}
}Run:
npm run assets:check
npm run assetsFor CI:
npx assets-toolkit doctor💎 Practical Tips
- 📁 Keep assets inside
assetsorsrc/assets. - 🧪 Run
doctorbefore production builds. - 🛠 Use
doctor --fixafter adding assets from designers. - 📌 Commit generated files if your team wants stable imports.
- ♻️ Run
cleanwhen switching branches.
🔗 Repository
GitHub:
https://github.com/YOUR_USERNAME/assets-toolkit
Report issues:
https://github.com/YOUR_USERNAME/assets-toolkit/issues
📄 License
This project is licensed under the MIT License.
See LICENSE for details.
