Folder Structure

Proper folder organization makes assets easy to find, maintain, and scale as your project grows.

Public Directory (/public/)

For static assets served directly without processing:

public/
├── images/
│   ├── logos/
│   │   ├── logo-company-light.svg
│   │   ├── logo-company-dark.svg
│   │   └── logo-company-icon.svg
│   ├── icons/
│   │   ├── icon-home-24.svg
│   │   ├── icon-search-24.svg
│   │   └── icon-user-24.svg
│   ├── og/
│   │   ├── og-home.jpg
│   │   └── og-about.jpg
│   └── favicons/
│       ├── favicon.ico
│       ├── favicon-16x16.png
│       └── favicon-32x32.png
├── videos/
│   ├── hero-animation-1080p.mp4
│   └── hero-animation-1080p.webm
├── fonts/
│   ├── inter-400-regular.woff2
│   ├── inter-700-bold.woff2
│   └── inter-400-italic.woff2
└── documents/
    └── brand-guidelines.pdf

Assets Directory (/assets/)

For assets processed by Vite (images, styles, etc):

assets/
├── images/
│   ├── hero/
│   │   ├── hero-background-desktop.jpg
│   │   ├── hero-background-tablet.jpg
│   │   └── hero-background-mobile.jpg
│   ├── products/
│   │   ├── product-thumbnail-01.jpg
│   │   └── product-thumbnail-02.jpg
│   └── content/
│       └── article-featured-image.jpg
├── styles/
│   ├── main.css
│   ├── variables.css
│   └── components/
│       └── button.css
└── svg/
    ├── illustrations/
    │   └── error-404.svg
    └── decorations/
        └── wave-divider.svg

Organization Principles

By Type vs. By Feature

By Type (Recommended for smaller projects):

/assets/images/
/assets/videos/
/assets/fonts/

By Feature (Recommended for larger projects):

/assets/home/images/
/assets/home/videos/
/assets/products/images/

Context-Based Organization

Group related assets together:

public/images/
├── brand/          # Brand-related assets
│   ├── logos/
│   └── colors/
├── marketing/      # Marketing materials
│   ├── campaigns/
│   └── banners/
└── ui/            # UI elements
    ├── icons/
    └── backgrounds/

Nuxt-Specific Considerations

Public vs Assets

Use /public/ when:

  • Assets are referenced directly in HTML
  • Files should be served as-is without processing
  • URLs need to be predictable (e.g., /images/logo.svg)
  • Third-party integrations require specific paths

Use /assets/ when:

  • Assets should be optimized/processed by Vite
  • Images need responsive variants
  • Assets are imported in components
  • You want cache-busting via hashed filenames

Import Aliases

Configure in nuxt.config.ts:

export default defineNuxtConfig({
  alias: {
    '@images': fileURLToPath(new URL('./assets/images', import.meta.url)),
    '@public': fileURLToPath(new URL('./public', import.meta.url)),
  }
})

Usage:

<script setup>
import heroImage from '@images/hero/hero-background.jpg'
</script>

Source Files Organization

Keep original, unoptimized assets separate:

src-assets/          # Git ignored, not in public repo
├── originals/
│   ├── images/
│   │   └── hero-background-original.psd
│   └── videos/
│       └── hero-animation-4k-uncompressed.mov
└── exports/         # Exported for web use
    └── images/

.gitignore:

src-assets/originals/
*.psd
*.ai
*.sketch

Scaling Considerations

Large Projects

For projects with hundreds of assets:

assets/
├── images/
│   ├── pages/
│   │   ├── home/
│   │   ├── about/
│   │   └── products/
│   └── shared/
│       ├── backgrounds/
│       └── decorations/

CDN Integration

For production deployments:

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    cdnURL: 'https://cdn.example.com'
  }
})

Best Practices

  • Keep folder depth reasonable (max 3-4 levels)
  • Use consistent naming across all folders
  • Document your structure in a README
  • Regular cleanup of unused assets
  • Use .gitkeep for empty directories

Example README

Create /assets/README.md:

# Assets Directory

## Structure
- `/images/hero/` - Homepage hero images
- `/images/products/` - Product imagery
- `/svg/` - SVG illustrations and icons

## Guidelines
- Use WebP format for photos
- SVG for logos and icons
- Max image size: 1920px width

Next Steps

Table of Contents