Asset Management

Asset management in Astro involves understanding where to place files and how they’re processed. The FiNAN website uses two directories for assets, each with different purposes.

Two Asset Directories

finan-website/
├── src/assets/           # Processed by Astro (optimized)
│   └── images/
│       └── committee/    # Committee member photos
└── public/               # Served as-is (not processed)
    ├── images/
    ├── favicon.svg
    └── robots.txt

src/assets/ - Optimized Assets

Use src/assets/ for images that need optimization.

When to Use src/assets/

✅ Committee member photos
✅ Hero background images
✅ Partner logos
✅ Any image referenced in Astro components
✅ Any image that needs responsive optimization

How It Works

When you import an image from src/assets/, Astro:

Optimizes - Converts to WebP/AVIF for modern browsers
Resizes - Generates multiple sizes for responsive images
Fingerprints - Adds content hash to filename for caching
Includes metadata - Width, height, format information

---
import type { CommitteeMember } from '@/data/representation/committee/types';

interface Props {
  members: CommitteeMember[];
}

const { members } = Astro.props;
---

<div class="members-grid">
  {members.map(member => (
    <div class="member-card">
      <!-- Image is optimized automatically -->
      <img
        src={member.photo.src}
        alt={member.name}
        width={member.photo.width}
        height={member.photo.height}
      />
      <h3>{member.name}</h3>
      <p>{member.position}</p>
    </div>
  ))}
</div>

import type { CommitteeData } from './types';

// Import images from src/assets/
import photoJohnDoe from '@/assets/images/committee/finland/john-doe.jpg';
import photoJaneSmith from '@/assets/images/committee/finland/jane-smith.jpg';

export const finlandCommittee: CommitteeData = {
  members: [
    {
      name: 'John Doe',
      position: 'President',
      photo: photoJohnDoe, // ImageMetadata object
      country: 'Finland',
    },
    {
      name: 'Jane Smith',
      position: 'Secretary',
      photo: photoJaneSmith, // ImageMetadata object
      country: 'Finland',
    },
  ],
  established: '2015',
  description: 'Supporting Filipino nurses in Finland',
};

Image Metadata

When you import an image, you get an ImageMetadata object:

import myPhoto from '@/assets/images/committee/finland/john-doe.jpg';

console.log(myPhoto);
// {
//   src: "/_astro/john-doe.a1b2c3d4.jpg",
//   width: 800,
//   height: 1000,
//   format: "jpg"
// }

This metadata is used for:

Setting proper width and height attributes (prevents layout shift)
Generating responsive srcset for different screen sizes
Type checking in TypeScript

public/ - Static Assets

Use public/ for assets that should be served as-is without processing.

When to Use public/

✅ favicon.svg or favicon.ico
✅ robots.txt
✅ sitemap.xml
✅ Social media images (og-image.jpg)
✅ Any file that needs a specific, unchanging URL
✅ Third-party assets (e.g., files from external sources)

How It Works

Files in public/ are:

Copied as-is - No optimization or processing
Served from root - /public/image.jpg becomes /image.jpg
Referenced by path - Use /image.jpg not @/public/image.jpg

Example: Using public/ Assets

---
const seo = {
  title: 'FiNAN',
  description: 'Filipino Nurses Association in the Nordic Region',
  ogImage: '/images/og-image.jpg', // Served from public/images/og-image.jpg
};
---

<head>
  <meta property="og:image" content={seo.ogImage} />
  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
</head>

Quick Reference for Editors

If you’re a content editor adding images, use this decision tree:

Where Should I Put This Image?

Is this a committee member photo?
  └─ YES → src/assets/images/committee/[country]/

Is this a logo or partner image?
  └─ YES → src/assets/images/partners/ or logos/

Is this a hero background or banner?
  └─ YES → src/assets/images/heroes/

Is this an Open Graph image for social media?
  └─ YES → public/images/

Is this a favicon or robots.txt?
  └─ YES → public/

Committee Photo Guidelines

Most important for content editors!

File Location

src/assets/images/committee/
├── finland/
│   ├── john-doe.jpg
│   ├── jane-smith.jpg
│   └── mike-johnson.jpg
├── sweden/
│   ├── anna-svensson.jpg
│   └── lars-andersson.jpg
├── norway/
│   └── ...
└── [other countries]/

File Naming Convention

Use kebab-case (lowercase with hyphens)
No spaces in filenames
Match member name for easy reference

✅ Correct
❌ Incorrect

john-doe.jpg
jane-smith.jpg
maria-garcia.jpg
anna-svensson.jpg

John Doe.jpg          # Has spaces
john_doe.jpg          # Uses underscores
JohnDoe.jpg           # Not lowercase
john-doe.png          # Inconsistent format (prefer .jpg)

Photo Requirements

Format: JPEG (.jpg) preferred for photos
Size: Minimum 400x500px, recommended 800x1000px
Aspect Ratio: Portrait orientation (4:5 ratio works well)
File Size: Under 500KB (Astro will optimize further)
Quality: High quality, well-lit, professional appearance

Adding Committee Photos (Step-by-Step)

Prepare the photo
- Save as JPEG format (.jpg)
- Use kebab-case filename: john-doe.jpg
- Ensure good quality and lighting
Upload to correct country folder

Navigate to src/assets/images/committee/[country]/ and add your photo.

Example for Finland: src/assets/images/committee/finland/john-doe.jpg
Import in committee data file

Open the committee file (e.g., src/data/representation/committee/finlandCommittee.ts):
```
// Add at the top with other imports
import photoJohnDoe from '@/assets/images/committee/finland/john-doe.jpg';
```
Variable name uses camelCase starting with “photo” (e.g., photoJohnDoe), but filename uses kebab-case (e.g., john-doe.jpg).

Add member to array

export const finlandCommittee: CommitteeData = {
  members: [
    {
      name: 'John Doe',
      position: 'President',
      photo: photoJohnDoe, // Use the imported variable
      country: 'Finland',
    },
    // ... other members
  ],
  // ...
};

Verify the build

Run pnpm build to ensure no errors. If successful, your image is properly configured!

Common Mistakes

1. Using String Paths Instead of Imports

❌ Wrong:

{
  name: 'John Doe',
  photo: '/images/committee/finland/john-doe.jpg', // String path
}

✅ Correct:

import photoJohnDoe from '@/assets/images/committee/finland/john-doe.jpg';

{
  name: 'John Doe',
  photo: photoJohnDoe, // Imported ImageMetadata object
}

2. Wrong File Path

❌ Wrong:

import photoJohnDoe from '@/assets/committee/finland/john-doe.jpg';
// Missing "images" in path

✅ Correct:

import photoJohnDoe from '@/assets/images/committee/finland/john-doe.jpg';

3. Mismatched Variable Naming

❌ Confusing:

import johnDoe from '@/assets/images/committee/finland/john-doe.jpg';

✅ Clear:

import photoJohnDoe from '@/assets/images/committee/finland/john-doe.jpg';

Convention: Use photo prefix for all committee member photo imports.

4. Wrong File Extension

❌ Wrong:

import photoJohnDoe from '@/assets/images/committee/finland/john-doe.png';
// File is actually .jpg

✅ Correct:

import photoJohnDoe from '@/assets/images/committee/finland/john-doe.jpg';

Image Optimization Details (For Developers)

How Astro Optimizes Images

When you build the site:

Format Conversion
- Generates WebP and AVIF versions for modern browsers
- Falls back to original format for older browsers
Responsive Sizes
- Creates multiple sizes: 400w, 800w, 1200w, 1600w
- Browser downloads appropriate size based on screen
Content Hashing
- Adds hash to filename: john-doe.a1b2c3d4.jpg
- Enables long-term caching without stale content
Metadata Extraction
- Embeds width and height for layout stability
- Prevents Cumulative Layout Shift (CLS)

Performance Benefits

Smaller File Sizes - WebP/AVIF are 25-50% smaller than JPEG
Faster Loading - Responsive images load appropriate sizes
Better SEO - Google rewards fast, stable page layouts
Improved Core Web Vitals - LCP and CLS improvements

Advanced: Using Astro’s Image Component

For more control, use Astro’s <Image> component:

---
import { Image } from 'astro:assets';
import heroImage from '@/assets/images/heroes/main-hero.jpg';
---

<Image
  src={heroImage}
  alt="FiNAN Hero"
  width={1920}
  height={1080}
  format="webp"
  quality={80}
  loading="lazy"
/>

Benefits:

Fine-tuned quality and format control
Lazy loading support
Automatic srcset generation

Troubleshooting

Build Error: Cannot Find Module

Error:

Cannot find module '@/assets/images/committee/finland/john-doe.jpg'

Solutions:

Check file exists at the exact path
Verify filename spelling and extension
Ensure using @/assets/ not @/public/

Image Not Displaying

Problem: Image shows broken link icon

Solutions:

Verify import is correct in data file
Check that photo property uses imported variable, not string
Run pnpm build to see if there are type errors

Type Error: Wrong Type for Photo

Error:

Type 'string' is not assignable to type 'ImageMetadata'

Solution: You’re using a string path instead of imported image:

// ❌ Wrong
photo: '/path/to/image.jpg'

// ✅ Correct
import photoName from '@/assets/images/committee/country/name.jpg';
photo: photoName

Next Steps

Committee Management

Complete step-by-step guide for managing committee members

View Guide →

Data Configuration

Learn how committee data is structured and typed

View Guide →

Creating Components

Learn how components use optimized images

View Guide →