Library Directory Structure#

This directory contains all shared code, components, and resources for the application.

Structure Overview#

src/lib/
├── assets/         # Static assets (images, icons, fonts, branding)
├── components/     # Reusable Svelte components
├── services/       # Business logic and API services
├── styles/         # Global styles and design tokens
├── types/          # TypeScript type definitions
├── utils/          # Utility functions and helpers
├── constants.ts    # Application constants and configuration
└── index.ts        # Main library exports

Directory Details#

assets/ - Static Assets#

Organized by asset type:

• assets/brand/ - Logo and brand assets
• assets/icons/ - Icon files (SVG, PNG)
• assets/images/ - Images and graphics
• assets/fonts/ - Custom font files

components/ - Svelte Components#

Organized by component type:

• components/layout/ - Layout components (Header, Hero, Footer)
• components/cards/ - Card components (ProjectCard, MemberCard)
• components/sections/ - Section components (ProjectGrid, MemberGrid, About)
• components/ui/ - Reusable UI components (Avatar, Button, Input)

Each component directory should include:

• Component .svelte files
• Component-specific types (if needed)
• Component index for exports

services/ - Business Logic#

Service modules organized by domain:

• services/atproto/ - AT Protocol integration
• Add more services as needed (API clients, data fetching, etc.)

styles/ - Global Styles#

• styles/open-props.css - Open Props imports
• styles/root-colours.css - Brand color tokens
• Additional global styles as needed

types/ - TypeScript Types#

Centralized type definitions:

• types/components.ts - Component prop types
• types/api.ts - API response types (when needed)
• types/models.ts - Data model types (when needed)

utils/ - Utilities#

Helper functions organized by purpose:

• String manipulation
• Date formatting
• Validation
• API helpers

Import Patterns#

Aliased Imports#

Use the $lib alias for all library imports:

// Components
import { Header, Hero, ProjectCard } from '$lib/components';

// Types
import type { Project, Member } from '$lib/types';

// Services
import { getListMembers } from '$lib/services/atproto';

// Utils
import { formatDate } from '$lib/utils/date';

// Constants
import { SITE_CONFIG, PROJECTS } from '$lib/constants';

Direct Imports#

For more specific imports or tree-shaking:

import Header from '$lib/components/layout/Header.svelte';
import type { Project } from '$lib/types/components';

Adding New Content#

Adding a Component#

1. Create the component in the appropriate subdirectory
2. Add to the component's index.ts
3. Export from components/index.ts if widely used

// src/lib/components/ui/Button.svelte
<script lang="ts">
  // Component code
</script>

// src/lib/components/index.ts
export { default as Button } from './ui/Button.svelte';

Adding a Type#

1. Add to appropriate file in types/
2. Export from types/index.ts

// src/lib/types/models.ts
export type User = {
  id: string;
  name: string;
};

// src/lib/types/index.ts
export type { User } from './models';

Adding a Utility#

1. Create utility file in utils/
2. Export functions
3. Optionally add to utils/index.ts

// src/lib/utils/string.ts
export function capitalize(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

Best Practices#

1. Organize by feature/type - Group related code together
2. Use index files - Simplify imports with barrel exports
3. Keep components focused - Single responsibility principle
4. Type everything - Leverage TypeScript for safety
5. Document complex code - Add comments for clarity
6. Test utilities - Write unit tests for helpers
7. Reuse components - Build composable, reusable pieces

File Naming Conventions#

• Components: PascalCase (e.g., ProjectCard.svelte)
• Types: camelCase or PascalCase (e.g., components.ts)
• Utilities: camelCase (e.g., dateUtils.ts)
• Constants: SCREAMING_SNAKE_CASE in file (e.g., SITE_CONFIG)
• Files: camelCase or kebab-case (e.g., apiHelpers.ts or api-helpers.ts)

Related Documentation#

• See docs/COMPONENTS.md for detailed component documentation
• See docs/LUCIDE_ICONS.md for icon usage
• See tests/README.md for testing guidelines