assets-toolkit 1.0.2 → 1.0.3

package/README.md

@@ -7,7 +7,15 @@
 ![typescript](https://img.shields.io/badge/TypeScript-ready-3178c6)
 ![platforms](https://img.shields.io/badge/platforms-RN%20%7C%20Expo%20%7C%20React%20%7C%20Next%20%7C%20Vite-7c3aed)
 
-Assets 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.
+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
 
 ```txt
 assets/                      generated-assets/
@@ -19,14 +27,16 @@ assets/                      generated-assets/
 
 ## ✨ Why Use It?
 
-- 🚀 Generate one tidy `Assets` object from images, SVGs, fonts, audio, video, and Lottie files.
-- 🗂️ Keep nested folder structure in the generated output.
-- 🧹 Detect duplicate files before they bloat your app.
-- 🛡️ Catch invalid filenames before Metro, Vite, Next.js, or CI complains.
-- 📊 Check large assets and platform support from one simple command.
-- ♻️ Clean generated files and cache whenever you want a fresh build.
+- 🚀 Generate one typed `Assets` object 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
+# 📦 Installation
 
 Install it as a development dependency:
 
@@ -40,64 +50,101 @@ Or run it directly with `npx`:
 npx assets-toolkit help
 ```
 
-## ⚡ Quick Start
+---
+
+# ⚡ Quick Start
 
 Put assets in one of the default folders:
 
 ```txt
 assets/
   logo.png
-  home@2x.png
   icons/
     search.svg
   fonts/
     Inter.ttf
 ```
 
-Generate the asset files:
+Generate asset files:
 
 ```sh
 npx assets-toolkit generate
 ```
 
-Import the generated output in your app:
+Import generated assets:
 
 ```ts
-import { Assets, images, svg, fonts } from "./generated-assets";
+import { Assets } from "./generated-assets";
 
 const logo = Assets.images.logo;
-const searchIcon = svg.icons.search;
-const interFont = fonts.fonts.Inter;
+const searchIcon = Assets.svg.images.search;
+const font = Assets.fonts.fonts.Inter;
 ```
 
-By default, Assets Toolkit looks in:
+---
+
+# 📁 Generated Location
+
+Assets Toolkit automatically detects your project structure.
+
+If your project contains a `src` folder:
 
 ```txt
-./src/assets
-./assets
+src/
+ ├── assets/
+ └── generated-assets/
 ```
 
-And writes generated files to:
+If your project does not contain a `src` folder:
 
 ```txt
-./generated-assets
+assets/
+generated-assets/
 ```
 
-## 🧭 CLI Commands
+You can always override this using:
+
+```json
+{
+  "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 common problems.                    |
-| `doctor --fix`    | Rename invalid files and remove duplicates after confirmation. |
-| `reports`         | Print asset statistics and project insights.                   |
-| `clean`, `-c`     | Remove generated files and cache.                              |
-| `--version`, `-v` | Show installed package version.                                |
-| `help`, `-h`      | Show CLI help.                                                 |
+| 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 from your project assets.
+# 🚀 Generate
+
+Generate asset maps:
 
 ```sh
 npx assets-toolkit generate
@@ -109,42 +156,64 @@ Alias:
 npx assets-toolkit -g
 ```
 
-Useful options:
+Options:
 
 ```sh
 npx assets-toolkit generate --outDir src/generated-assets
-npx assets-toolkit generate -o src/generated-assets
 npx assets-toolkit generate --assetsDir assets
 npx assets-toolkit generate --assetsDirs assets,src/shared/assets
 ```
 
-What it does:
+The generator creates:
 
-- Creates generated category files like `images-generate.ts`, `svg-generate.ts`, and `fonts-generate.ts`.
-- Creates a generated `index.ts` that exports `Assets` plus each category.
-- Preserves nested folders as nested object keys.
-- Skips invalid asset filenames.
-- Reports duplicate files and validation warnings.
+```txt
+generated-assets/
 
-### `doctor`
+ index.ts
+ images-generate.ts
+ svg-generate.ts
+ fonts-generate.ts
+ audio-generate.ts
+ video-generate.ts
+ lottie-generate.ts
+```
 
-🩺 Inspect your asset setup and find issues before they become runtime problems.
+Generated output:
+
+```ts
+export const Assets = {
+  images,
+  svg,
+  fonts,
+  audio,
+  video,
+  lottie,
+} as const;
+```
+
+---
+
+# 🩺 Doctor
+
+Check your asset setup:
 
 ```sh
 npx assets-toolkit doctor
 ```
 
-Checks include:
+Checks:
 
-- Missing asset directories
+- Missing asset folders
 - Invalid filenames
 - Duplicate assets
-- Unsupported platform assets
-- Large files over the recommended threshold
+- Unsupported formats
+- Large files
+
+---
 
-### `doctor --fix`
+# 🛠 Doctor Fix
 
-🛠️ Preview and fix invalid asset filenames.
+Preview fixes:
 
 ```sh
 npx assets-toolkit doctor --fix
@@ -162,22 +231,25 @@ This command can:
 - Avoid collisions with files that already exist.
 - Remove duplicate asset files after confirmation.
 
-### `reports`
+---
 
-📊 Show a project asset report.
+# 📊 Reports
+
+Generate an asset report:
 
 ```sh
 npx assets-toolkit reports
 ```
 
-The report includes:
+Includes:
 
-- Current configuration
-- Asset counts by category
+- Asset counts
 - Storage usage
-- Largest assets
+- Largest files
 - Extension breakdown
-- Generated output status
+- Generated output information
+
+---
 
 ### `clean`
 
@@ -213,11 +285,15 @@ npx assets-toolkit help
 npx assets-toolkit -h
 ```
 
-## ⚙️ Configuration
+# ⚙️ Configuration
 
-On first use, Assets Toolkit creates `assets-toolkit.config.json` if it does not already exist.
+On first run, Assets Toolkit creates:
 
-Default config:
+```txt
+assets-toolkit.config.json
+```
+
+Default:
 
 ```json
 {
@@ -228,6 +304,8 @@ Default config:
 }
 ```
 
+---
+
 ### Config Options
 
 | Option       | Type       | Description                                                                                                                                                    |
@@ -237,84 +315,67 @@ Default config:
 | `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`.                            |
 
-Example:
+---
 
-```json
-{
-  "assets": ["./assets", "./src/shared/assets"],
-  "output": "src/generated-assets",
-  "target": "react-native",
-  "duplicates": "warn"
-}
+# 🧩 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:
+
+```ts
+export const images = {
+  logo: new URL("../assets/images/logo.png", import.meta.url).href,
+};
 ```
 
-## 🧩 Supported Assets
+This allows bundlers like:
+
+- Webpack
+- Turbopack
+- Vite
 
-| Category | Extensions                                                                                           |
-| -------- | ---------------------------------------------------------------------------------------------------- |
-| Images   | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`, `.heic`, `.heif`, `.avif`, `.tiff`, `.tif`, `.ico` |
-| SVG      | `.svg`                                                                                               |
-| Fonts    | `.ttf`, `.otf`, `.woff`, `.woff2`                                                                    |
-| Audio    | `.mp3`, `.wav`, `.aac`, `.m4a`, `.ogg`, `.flac`, `.amr`, `.opus`, `.caf`, `.aiff`                    |
-| Video    | `.mp4`, `.mov`, `.m4v`, `.avi`, `.mkv`, `.webm`, `.3gp`, `.mpeg`, `.mpg`                             |
-| Lottie   | `.lottie`, plus valid Lottie `.json` files                                                           |
+to correctly resolve assets.
 
-## ✅ Filename Rules
+---
 
-Use simple, portable filenames:
+# ✅ Filename Rules
+
+Recommended:
 
 ```txt
 logo.png
 logo-dark.svg
 home@2x.png
-home@3x.png
 Inter.ttf
 ```
 
 Avoid:
 
 ```txt
-bad name.png
+my logo.png
 bad!name.svg
-logo.PNG
-___.png
-```
-
-Safe filenames make generated keys cleaner and reduce cross-platform build issues.
-
-## 🏗️ Generated Output
-
-After running `generate`, you will get output similar to:
-
-```txt
-generated-assets/
-  index.ts
-  images-generate.ts
-  svg-generate.ts
-  fonts-generate.ts
-  audio-generate.ts
-  video-generate.ts
-  lottie-generate.ts
+LOGO.PNG
 ```
 
-Example generated shape:
+Clean filenames produce predictable generated keys.
 
-```ts
-export const Assets = {
-  images,
-  svg,
-  fonts,
-  audio,
-  video,
-  lottie,
-} as const;
-```
+---
 
-Nested folders become nested object keys, so your file layout stays readable in code.
+# 🧪 Recommended Workflow
 
-## 🧪 Recommended Workflow
-
-Add these scripts to your project:
+Add scripts:
 
 ```json
 {
@@ -328,27 +389,45 @@ Add these scripts to your project:
 }
 ```
 
-Then run:
+Run:
 
 ```sh
 npm run assets:check
 npm run assets
 ```
 
-For CI, a simple check is often enough:
+For CI:
 
 ```sh
 npx assets-toolkit doctor
 ```
 
-## 💎 Practical Tips
+---
+
+# 💎 Practical Tips
+
+- 📁 Keep assets inside `assets` or `src/assets`.
+- 🧪 Run `doctor` before production builds.
+- 🛠 Use `doctor --fix` after adding assets from designers.
+- 📌 Commit generated files if your team wants stable imports.
+- ♻️ Run `clean` when switching branches.
+
+---
+
+# 🔗 Repository
+
+GitHub:
+
+https://github.com/YOUR_USERNAME/assets-toolkit
+
+Report issues:
+
+https://github.com/YOUR_USERNAME/assets-toolkit/issues
+
+---
 
-- 📁 Keep app assets in `assets` or `src/assets` for zero-config usage.
-- 🧪 Run `doctor` before release builds to catch large, duplicate, or unsupported files.
-- 🛠️ Use `doctor --fix` when designers or teammates add files with spaces or special characters.
-- 📌 Commit generated assets only if your team wants stable generated files in source control.
-- ♻️ Run `clean` when switching branches if generated output looks stale.
+# 📄 License
 
-## 📄 License
+This project is licensed under the MIT License.
 
-This project is licensed under the [MIT License](LICENSE).
+See [LICENSE](LICENSE) for details.

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./runtime.js";
+export * from "./rn-assets.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export * from "./runtime.js";
+export * from "./rn-assets.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assets-toolkit",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Type-safe asset management CLI for React Native, Expo, React, Next.js and Vite. Automatically scans, validates and generates typed asset imports.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",