---
description: when doing anything with capacitor assets
alwaysApply: false
---

# Asset Configuration Directive

**Author**: Matthew Raymer
**Date**: 2025-08-19
**Status**: 🎯 **ACTIVE** - Asset management guidelines

*Scope: Assets Only (icons, splashes, image pipelines) — not overall build
orchestration*

## Intent

- Version **asset configuration files** (optionally dev-time generated).

- **Do not** version platform asset outputs (Android/iOS/Electron); generate

  them **at build-time** with standard tools.

- Keep existing per-platform build scripts unchanged.

## Source of Truth

- **Preferred (Capacitor default):** `resources/` as the single master source.

- **Alternative:** `assets/` is acceptable **only** if `capacitor-assets` is

  explicitly configured to read from it.

- **Never** maintain both `resources/` and `assets/` as parallel sources.

  Migrate and delete the redundant folder.

## Config Files

- Live under: `config/assets/` (committed).

- Examples:

  - `config/assets/capacitor-assets.config.json` (or the path the tool

    expects)

  - `config/assets/android.assets.json`

  - `config/assets/ios.assets.json`

  - `config/assets/common.assets.yaml` (optional shared layer)

- **Dev-time generation allowed** for these configs; **build-time

  generation is forbidden**.

## Build-Time Behavior

- Build generates platform assets (not configs) using the standard chain:

```bash

npm run build:capacitor        # web build via Vite (.mts)
npx cap sync
npx capacitor-assets generate  # produces platform assets; not committed

# then platform-specific build steps

```

---

**Status**: Active asset management directive
**Priority**: Medium
**Estimated Effort**: Ongoing reference
**Dependencies**: capacitor-assets toolchain
**Stakeholders**: Development team, Build team

  npx capacitor-assets generate  # produces platform assets; not committed

# then platform-specific build steps

## Model Implementation Checklist

### Before Asset Configuration

- [ ] **Source Review**: Identify current asset source location (`resources/` or
  `assets/`)
- [ ] **Tool Assessment**: Verify capacitor-assets toolchain is available
- [ ] **Config Planning**: Plan configuration file structure and location
- [ ] **Platform Analysis**: Understand asset requirements for all target platforms

### During Asset Configuration

- [ ] **Source Consolidation**: Ensure single source of truth (prefer `resources/`)
- [ ] **Config Creation**: Create platform-specific asset configuration files
- [ ] **Tool Integration**: Configure capacitor-assets to read from correct source
- [ ] **Build Integration**: Integrate asset generation into build pipeline

### After Asset Configuration

- [ ] **Build Testing**: Verify assets generate correctly at build time
- [ ] **Platform Validation**: Test asset generation across all platforms
- [ ] **Documentation**: Update build documentation with asset generation steps
- [ ] **Team Communication**: Communicate asset workflow changes to team