Project Structure

Understanding how Irresistible projects are organized for optimal development workflow.

Overview

Irresistible projects follow a consistent structure that promotes:

• Clear organization - Easy to navigate and understand
• Scalability - Grows with your application
• Best practices - Industry-standard patterns
• Framework flexibility - Adapts to your chosen framework

Basic Structure

my-app/
├── src/                    # Source code
│   ├── routes/            # Page routes (SvelteKit/Next.js)
│   ├── components/        # Reusable components
│   ├── lib/              # Utilities and helpers
│   ├── styles/           # Global styles
│   └── app.html          # HTML template
├── static/               # Static assets
├── tests/                # Test files
├── .env                  # Environment variables
├── .env.example          # Environment template
├── irresistible.config.js # Project configuration
├── package.json          # Dependencies
└── README.md            # Project documentation

Directory Breakdown

/src

The main source directory containing all your application code.

/src/routes

Page-based routing for frameworks like SvelteKit and Next.js:

routes/
├── +page.svelte          # Homepage (/)
├── about/
│   └── +page.svelte     # /about
├── blog/
│   ├── +page.svelte     # /blog
│   └── [slug]/
│       └── +page.svelte # /blog/post-title
└── api/
    └── users/
        └── +server.ts   # API endpoint

/src/components

Reusable UI components:

components/
├── common/
│   ├── Button.svelte
│   ├── Input.svelte
│   └── Modal.svelte
├── layout/
│   ├── Header.svelte
│   ├── Footer.svelte
│   └── Sidebar.svelte
└── features/
    ├── UserProfile.svelte
    └── SearchBar.svelte

/src/lib

Shared utilities and business logic:

lib/
├── api/
│   ├── client.ts        # API client
│   └── endpoints.ts     # API endpoints
├── stores/
│   ├── auth.ts         # Auth state
│   └── user.ts         # User state
├── utils/
│   ├── dates.ts        # Date helpers
│   └── validation.ts   # Form validation
└── types/
    └── index.ts        # TypeScript types

/static

Static assets served directly:

static/
├── images/
│   ├── logo.svg
│   └── hero.jpg
├── fonts/
│   └── custom-font.woff2
├── favicon.ico
└── robots.txt

/tests

Testing structure:

tests/
├── unit/
│   ├── components/
│   └── utils/
├── integration/
│   └── api/
└── e2e/
    └── user-flows/

Configuration Files

irresistible.config.js

Main project configuration:

export default {
  // Project metadata
  name: 'my-app',
  version: '1.0.0',
  
  // Framework settings
  framework: 'sveltekit',
  
  // Build configuration
  build: {
    output: 'build',
    target: 'node18',
    minify: true
  },
  
  // Deployment settings
  deploy: {
    provider: 'irresistible',
    region: 'us-east-1',
    environment: {
      production: {
        url: 'https://myapp.com'
      },
      staging: {
        url: 'https://staging.myapp.com'
      }
    }
  },
  
  // AI Assistant configuration
  ai: {
    personality: 'professional',
    contextFiles: ['README.md', 'ARCHITECTURE.md']
  },
  
  // Integrations
  integrations: {
    github: {
      repo: 'username/my-app'
    },
    slack: {
      webhook: process.env.SLACK_WEBHOOK
    }
  }
}

package.json

Dependencies and scripts:

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "irresistible dev",
    "build": "irresistible build",
    "preview": "irresistible preview",
    "deploy": "irresistible deploy",
    "test": "vitest",
    "lint": "eslint src",
    "format": "prettier --write ."
  },
  "dependencies": {
    "@irresistible/sdk": "^1.0.0",
    "svelte": "^4.0.0"
  },
  "devDependencies": {
    "@irresistible/cli": "^1.0.0",
    "vitest": "^1.0.0",
    "eslint": "^8.0.0",
    "prettier": "^3.0.0"
  }
}

Environment Files

.env - Local environment variables:

# API Keys
IRRESISTIBLE_API_KEY=your_api_key
DATABASE_URL=postgresql://localhost/myapp

# Third-party services
STRIPE_SECRET_KEY=sk_test_...
SENDGRID_API_KEY=SG...

# Feature flags
ENABLE_BETA_FEATURES=true

.env.example - Template for team members:

# Copy this to .env and fill in your values
IRRESISTIBLE_API_KEY=
DATABASE_URL=
STRIPE_SECRET_KEY=
SENDGRID_API_KEY=
ENABLE_BETA_FEATURES=false

Framework-Specific Structures

SvelteKit

src/
├── routes/
│   ├── +layout.svelte    # Root layout
│   ├── +page.svelte      # Homepage
│   └── +error.svelte     # Error page
├── app.d.ts              # App types
└── hooks.server.ts       # Server hooks

Next.js

src/
├── app/
│   ├── layout.tsx        # Root layout
│   ├── page.tsx          # Homepage
│   └── api/              # API routes
├── components/
└── lib/

Nuxt

├── pages/
│   └── index.vue         # Homepage
├── components/
├── composables/          # Vue composables
├── server/
│   └── api/              # Server routes
└── nuxt.config.ts        # Nuxt config

Advanced Patterns

Monorepo Structure

For larger projects:

my-workspace/
├── apps/
│   ├── web/              # Main web app
│   ├── admin/            # Admin panel
│   └── mobile/           # Mobile app
├── packages/
│   ├── ui/               # Shared UI components
│   ├── utils/            # Shared utilities
│   └── config/           # Shared configs
├── package.json          # Workspace config
└── irresistible.config.js

Feature-Based Structure

Organize by feature instead of file type:

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── api/
│   │   ├── stores/
│   │   └── index.ts
│   ├── dashboard/
│   │   ├── components/
│   │   ├── api/
│   │   └── index.ts
│   └── billing/
│       ├── components/
│       ├── api/
│       └── index.ts
├── shared/
└── routes/

Domain-Driven Structure

For complex applications:

src/
├── domains/
│   ├── user/
│   │   ├── entities/
│   │   ├── services/
│   │   ├── repositories/
│   │   └── controllers/
│   ├── product/
│   └── order/
├── infrastructure/
│   ├── database/
│   └── external/
└── presentation/
    ├── routes/
    └── components/

Best Practices

1. Naming Conventions

Files and Folders

• kebab-case for files: user-profile.svelte
• PascalCase for components: UserProfile.svelte
• camelCase for utilities: formatDate.ts

Variables and Functions

// Constants
const API_KEY = 'abc123';

// Functions
function getUserById(id) {}

// Classes
class UserService {}

// Interfaces/Types
interface User {}
type UserRole = 'admin' | 'user';

2. Component Organization

Flat vs Nested

// Flat (simple projects)
components/
├── Button.svelte
├── Card.svelte
└── Modal.svelte

// Nested (complex projects)
components/
├── common/
│   └── Button/
│       ├── Button.svelte
│       ├── Button.test.ts
│       └── Button.stories.ts
└── features/
    └── UserProfile/
        ├── UserProfile.svelte
        ├── UserAvatar.svelte
        └── UserStats.svelte

3. Import Aliases

Configure in irresistible.config.js:

export default {
  aliases: {
    '$components': './src/components',
    '$lib': './src/lib',
    '$utils': './src/lib/utils',
    '$stores': './src/lib/stores',
    '$types': './src/types'
  }
}

Use in your code:

import Button from '$components/Button.svelte';
import { formatDate } from '$utils/dates';
import type { User } from '$types';

4. Code Splitting

Organize for optimal loading:

routes/
├── (app)/              # Authenticated routes
│   ├── +layout.svelte  # Auth check
│   ├── dashboard/
│   └── settings/
├── (marketing)/        # Public routes
│   ├── +layout.svelte  # Marketing layout
│   ├── pricing/
│   └── about/
└── (auth)/             # Auth routes
    ├── login/
    └── signup/

Migration Guide

From Create React App

1. Move src/App.js → src/routes/+page.jsx
2. Move components to src/components/
3. Update imports to use aliases
4. Add irresistible.config.js

From Vue CLI

1. Move src/views/ → src/routes/
2. Move src/router/ → Use file-based routing
3. Update component imports
4. Configure build settings

From Plain HTML

1. Move HTML files to src/routes/
2. Convert to components
3. Move assets to static/
4. Add package.json

Troubleshooting

Common Issues

Import errors

• Check alias configuration
• Verify file extensions
• Ensure proper casing

Build failures

• Check for circular dependencies
• Verify environment variables
• Clear build cache

Route not found

• Check file naming
• Verify route structure
• Clear .irresistible cache

Next Steps

• Learn about routing patterns
• Explore component architecture
• Set up testing structure
• Configure CI/CD pipeline