diff --git a/README.md b/README.md index e175223..febd98d 100644 --- a/README.md +++ b/README.md @@ -93,8 +93,6 @@ Start your dev server and access the Asset Manager in three ways: ### Nuxt Module -For Nuxt 3/4 projects, use the official module for automatic integration: - ```bash npm install @vite-asset-manager/nuxt -D ``` @@ -106,70 +104,26 @@ export default defineNuxtConfig({ }) ``` -Features: -- Automatic floating icon injection (no manual setup) -- Nuxt DevTools integration -- Supports Nuxt 3 and 4 directory structures -- Dev-only (zero production footprint) +Zero-config with automatic floating icon injection, Nuxt DevTools integration, and Nuxt 3/4 support. See the **[full Nuxt documentation](https://www.npmjs.com/package/@vite-asset-manager/nuxt)** for all options. ### Next.js Integration -For Next.js 14+ projects, use the official integration package: - ```bash npm install nextjs-asset-manager -D ``` -**Step 1:** Wrap your Next.js config to suppress dev server request logging: - -```ts -// next.config.ts -import type { NextConfig } from "next" -import { withAssetManager } from "nextjs-asset-manager" - -const nextConfig: NextConfig = {} -export default withAssetManager(nextConfig) -``` - -**Step 2:** Create an API catch-all route: - ```ts // app/api/asset-manager/[[...path]]/route.ts import { createHandler } from 'nextjs-asset-manager' - const { GET, POST } = createHandler() export { GET, POST } ``` -**Step 3:** Add the client component to your root layout: - -```tsx -// app/layout.tsx -import { AssetManagerScript } from 'nextjs-asset-manager' - -export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - - {children} - - - - ) -} -``` - -Features: -- Dev-only (returns 404 in production) -- Automatic floating icon injection via client component -- Suppresses asset manager request logging in dev server -- Default base path: `/api/asset-manager` -- Singleton management for HMR stability -- Composable with other `withX` plugins (`withSentryConfig`, `withBundleAnalyzer`, etc.) +Three-step setup: wrap config, add route handler, add client component. See the **[full Next.js documentation](https://www.npmjs.com/package/nextjs-asset-manager)** for all options. ### Other SSR Frameworks -For SSR frameworks (Remix, SvelteKit, Solid Start), manual script injection is required. See the **[SSR Integration Guide](./docs/SSR_INTEGRATION.md)** for setup instructions. +For TanStack Start, Remix, SvelteKit, and Solid Start, manual script injection is required. See the **[SSR Integration Guide](./docs/SSR_INTEGRATION.md)** for setup instructions. ## Configuration diff --git a/docs/SSR_INTEGRATION.md b/docs/SSR_INTEGRATION.md index 9a7d17b..2da0505 100644 --- a/docs/SSR_INTEGRATION.md +++ b/docs/SSR_INTEGRATION.md @@ -1,178 +1,27 @@ # SSR Framework Integration Guide -This guide explains how to integrate the Vite Plugin Asset Manager with Server-Side Rendering (SSR) frameworks. +This guide covers **manual script injection** for SSR frameworks that don't have an official integration package. -## Overview +## Official Integration Packages -The plugin uses two injection methods depending on your framework: +If you're using **Nuxt** or **Next.js**, use the official packages instead of manual setup: -1. **Automatic (transformIndexHtml)**: For frameworks with static `index.html` files - ✅ React, Vue, Svelte, Solid, Preact, Lit, Qwik, Vanilla - -2. **Official Framework Packages**: Native integration with auto-injection - ✅ Nuxt (`@vite-asset-manager/nuxt`) - ✅ Next.js (`nextjs-asset-manager`) - -3. **Manual Component Injection**: For other SSR frameworks - ⚠️ TanStack Start, Remix, SvelteKit, Solid Start +- **Nuxt 3/4**: [`@vite-asset-manager/nuxt`](https://www.npmjs.com/package/@vite-asset-manager/nuxt) — zero-config module with automatic floating icon injection and DevTools integration +- **Next.js 14+**: [`nextjs-asset-manager`](https://www.npmjs.com/package/nextjs-asset-manager) — App Router route handlers with automatic floating icon via client component --- -## Why Manual Setup is Needed for SSR +## Why Manual Setup is Needed SSR frameworks dynamically generate HTML and don't use static `index.html` files. This means: - The `transformIndexHtml()` Vite hook is not called (no static HTML file exists) - Scripts must be injected directly in the SSR component tree -- This applies to all modern SSR frameworks (TanStack Start, Remix, Nuxt, SvelteKit, Solid Start) **The Solution**: Add the floating icon scripts directly in your framework's root component. --- -## Next.js Setup - -### Recommended: Official Next.js Package - -The easiest way to use Asset Manager with Next.js is via the official package `nextjs-asset-manager`: - -#### Step 1: Install the Package - -```bash -npm install nextjs-asset-manager -D -# or -pnpm add nextjs-asset-manager -D -``` - -#### Step 2: Wrap Your Next.js Config - -Wrap your `next.config.ts` with `withAssetManager` to automatically suppress dev server request logging for asset manager API routes: - -```typescript -// next.config.ts -import type { NextConfig } from "next" -import { withAssetManager } from "nextjs-asset-manager" - -const nextConfig: NextConfig = { - // Your existing config -} - -export default withAssetManager(nextConfig) -``` - -If you use a custom base path, pass it as an option: - -```typescript -export default withAssetManager(nextConfig, { base: '/api/assets' }) -``` - -#### Step 3: Create an API Route Handler - -Create a catch-all API route to handle all Asset Manager requests: - -```typescript -// app/api/asset-manager/[[...path]]/route.ts -import { createHandler } from 'nextjs-asset-manager' - -const { GET, POST } = createHandler({ - // Optional: customize settings - include: ['src', 'public', 'app'], // Directories to scan (default: ['app', 'public', 'src']) - launchEditor: 'code', // Editor for "Open in Editor" (default: 'code') - watch: true, // Real-time updates (default: true) - debug: false, // Enable debug logging - aliases: { '@/': 'src/' }, // Path aliases for import detection -}) - -export { GET, POST } -``` - -#### Step 4: Add the Client Component - -Add `AssetManagerScript` to your root layout for floating icon injection: - -```tsx -// app/layout.tsx -import { AssetManagerScript } from 'nextjs-asset-manager' - -export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - - {children} - - - - ) -} -``` - -That's it! The package automatically: -- ✅ Suppresses dev server request logging for asset manager routes -- ✅ Creates API endpoints for asset management -- ✅ Injects the floating icon (no manual script injection) -- ✅ Only runs in development mode (returns 404 in production) -- ✅ Survives Next.js HMR re-evaluation (globalThis singleton) - -#### Step 5: Access the Dashboard - -- **Floating Icon**: Click the overlay button or press `Option+Shift+A` (⌥⇧A) -- **Direct URL**: Visit `http://localhost:3000/api/asset-manager/` - -### Next.js-Specific Notes - -**Default Base Path**: The default base path is `/api/asset-manager` instead of `/__asset_manager__`. This is because Next.js treats folders starting with `_` as [private folders](https://nextjs.org/docs/app/getting-started/project-structure#private-folders) and excludes them from routing. - -**Custom Base Path**: If you want a different base path, update the config wrapper, handler, and component: - -```typescript -// next.config.ts -export default withAssetManager(nextConfig, { base: '/api/assets' }) - -// route.ts -const { GET, POST } = createHandler({ base: '/api/assets' }) - -// layout.tsx - -``` - -**Composing with Other Plugins**: `withAssetManager` follows the standard `withX` convention used by `@sentry/nextjs`, `@next/bundle-analyzer`, `next-intl`, etc. Compose by nesting — the innermost wrapper runs first: - -```typescript -// next.config.ts -import { withAssetManager } from "nextjs-asset-manager" -import { withSentryConfig } from "@sentry/nextjs" - -const nextConfig: NextConfig = {} - -// Nesting: each wrapper receives the output of the inner one -export default withSentryConfig(withAssetManager(nextConfig)) -``` - -For many plugins, a helper function can improve readability: - -```typescript -import { withAssetManager } from "nextjs-asset-manager" -import { withSentryConfig } from "@sentry/nextjs" -import withBundleAnalyzer from "@next/bundle-analyzer" - -const nextConfig: NextConfig = {} - -const compose = (...fns: ((c: NextConfig) => NextConfig)[]) => - fns.reduceRight((config, fn) => fn(config), nextConfig) - -export default compose( - withSentryConfig, - withBundleAnalyzer({ enabled: process.env.ANALYZE === "true" }), - withAssetManager, -) -``` - -**Web API Adapter**: Next.js App Router uses Web API `Request`/`Response` objects, while the core middleware uses Node.js HTTP. The package includes an adapter that bridges these transparently. - -**HMR Singleton**: The package uses a `globalThis` singleton pattern (similar to Prisma) to prevent re-initialization during Next.js hot module replacement. - ---- - ## TanStack Start Setup ### Step 1: Add Scripts to Root Component @@ -368,124 +217,6 @@ export default function Root() { --- -## Nuxt Setup - -### Recommended: Official Nuxt Module - -The easiest way to use Asset Manager with Nuxt is via the official module `@vite-asset-manager/nuxt`: - -#### Step 1: Install the Module - -```bash -npm install @vite-asset-manager/nuxt -# or -pnpm add @vite-asset-manager/nuxt -``` - -#### Step 2: Add to Nuxt Config - -```typescript -// nuxt.config.ts -export default defineNuxtConfig({ - modules: ['@vite-asset-manager/nuxt'], - - // Optional: customize settings - assetManager: { - base: '/__asset_manager__', // Default - include: ['assets', 'public'], // Directories to scan - floatingIcon: true, // Show floating icon - watch: true, // Real-time updates - launchEditor: 'code', // Editor for "Open in Editor" - devtools: true, // Add Nuxt DevTools tab - debug: false // Enable debug logging - } -}) -``` - -That's it! The module automatically: -- ✅ Injects the floating icon (no manual script injection) -- ✅ Handles Nuxt 3 and Nuxt 4 directory structure differences -- ✅ Adds an Asset Manager tab to Nuxt DevTools -- ✅ Only runs in development mode - -#### Step 3: Access the Dashboard - -- **Floating Icon**: Click the overlay button or press `Option+Shift+A` (⌥⇧A) -- **Direct URL**: Visit `http://localhost:3000/__asset_manager__/` -- **Nuxt DevTools**: Open DevTools (Shift+Option+D) and find the "Asset Manager" tab - ---- - -### Alternative: Manual Vite Plugin Setup - -If you prefer manual configuration or need more control, you can use the Vite plugin directly: - -#### Step 1: Configure the Plugin - -Add the plugin to your `nuxt.config.ts` using the `vite` configuration option: - -> **Important for Nuxt 4**: Nuxt 4 sets Vite's root to the `app/` directory. You must configure paths relative to `app/`, include source directories for unused asset detection, and set up aliases correctly. - -```typescript -// nuxt.config.ts -import AssetManager from 'vite-plugin-asset-manager' - -export default defineNuxtConfig({ - vite: { - plugins: [ - AssetManager({ - // Paths are relative to app/ directory (Nuxt's Vite root) - // Include both asset directories AND source directories - include: [ - 'assets', // app/assets/ - your assets - '../public', // public/ - static files (one level up from app/) - 'components', // For unused asset detection - 'pages', - 'layouts', - 'composables', - 'plugins' - ], - // Configure aliases to match Nuxt's path resolution - aliases: { - '@/': 'assets/', // @/image.png → assets/image.png - '~/': '' // ~/assets/image.png → assets/image.png - }, - // Enable debug mode if assets aren't showing - debug: true - }) - ] - } -}) -``` - -#### Step 2: Add Scripts to Root Component - -For Nuxt 3, create or edit `app.vue`: - -```vue - - -