File Organization Patterns

This reference documents the file organization patterns used throughout the codebase, including glob patterns for locating specific file types.

Directory Structure

Pages Directory

src/pages/
├── {routeName}/
│   ├── index.astro              # Page component
│   ├── _graphql/                # Page-specific GraphQL (underscore prefix hides from routing)
│   │   ├── page.query.graphql   # Main page query
│   │   ├── api.ts               # API functions
│   │   └── transform.ts         # Data transformations
│   ├── _components/             # Page-specific components (underscore prefix)
│   │   └── feature/
│   │       ├── Feature.astro
│   │       └── Feature.tsx
│   └── [...slug].astro          # Dynamic route segment

Components Directory

src/components/
├── feature/
│   ├── index.ts                 # Exports
│   ├── feature.tsx              # Component implementation
│   ├── feature.test.ts          # Component tests
│   ├── graphql/                 # Component-specific GraphQL
│   │   ├── query.graphql
│   │   ├── api.ts
│   │   └── transform.ts
│   └── utils.ts                 # Feature utilities

GraphQL Directory

src/graphql/
├── fragments/                    # Shared fragments
│   ├── imageProps.fragment.graphql
│   └── articleListItem.fragment.graphql
├── generated/                    # Auto-generated types
│   └── contentful/
│       └── schema.ts
└── codegen.ts                    # Codegen configuration

File Naming Patterns

GraphQL Files

Pattern	Description	Example
*.query.graphql	Query operations	page.query.graphql
*.mutation.graphql	Mutation operations	submit.mutation.graphql
*.fragment.graphql	Reusable fragments	imageProps.fragment.graphql
*.cms.graphql	Contentful queries (for codegen)	pageQuery.cms.graphql
*.api.graphql	API queries (internal)	validate.api.graphql

TypeScript Files

Pattern	Description	Example
api.ts	API functions	api.ts
transform.ts	Data transformations	transform.ts
transform.types.ts	Transform type definitions	transform.types.ts
utils.ts	Utility functions	utils.ts
*.test.ts	Test files	feature.test.ts

Component Files

Pattern	Description	Example
{name}.tsx	SolidJS component	newsletterForm.tsx
{name}.astro	Astro component	PageHeader.astro
index.ts	Module exports	index.ts

Directory Naming Conventions

Prefixed Directories

Prefix	Purpose	Example
_ (underscore)	Hidden from Astro routing	_graphql/, _components/
None	Standard feature/component directories	components/header/

Route Directories

Pattern	Description	Example
{name}	Static route	articles/
[param]	Dynamic route segment	[slug]/
[...slug]	Rest parameters	[...slug].astro

Location Rules

Page-Specific Files

Rule: Page-specific files must be in a directory with an underscore prefix to prevent Astro from creating routes for them.

✅ src/pages/articles/_graphql/api.ts
✅ src/pages/articles/_components/related.tsx

❌ src/pages/articles/graphql/api.ts        # Wrong: creates /articles/graphql route
❌ src/pages/articles/components/related.tsx # Wrong: creates /articles/components route

Component GraphQL Files

Rule: Component GraphQL files can use either graphql/ or _graphql/ depending on context:

✅ src/components/header/graphql/query.graphql     # Shared component
✅ src/pages/articles/_components/hero/graphql/    # Page component

Shared Fragments

Rule: Shared GraphQL fragments must be in src/graphql/fragments/:

✅ src/graphql/fragments/imageProps.fragment.graphql

❌ src/components/image/fragments/imageProps.fragment.graphql

Import Path Patterns

Use TypeScript path aliases for cleaner imports:

// ✅ Using path aliases
import { graphqlApi } from "#graphql/graphqlClient";
import type { Article } from "#types/content";
import FRAGMENT from "#graphql/fragments/image.fragment.graphql";

// ❌ Relative paths
import { graphqlApi } from "../../../graphql/graphqlClient";
import type { Article } from "../../../types/content";

Related

• Function Naming - API function naming conventions
• GraphQL Naming - GraphQL operation naming patterns
• Component Architecture Guide - How components are organized (guide)