Project Structure

Overview

Webiny projects follow a clean, simple structure designed for clarity and maintainability. All configuration is centralized, custom code has a dedicated location, and the project uses standard JavaScript/TypeScript conventions.

Directory Structure

Key Files

webiny.config.tsx

The central configuration file for your project. This is where you:

• Register extensions
• Configure AWS infrastructure
• Set up authentication providers
• Define deployment settings

Extensions/

The workspace for all custom code. Extensions are organized by type:

Reference extensions in webiny.config.tsx:

package.json

Contains project dependencies with key Webiny packages:

Key packages:

• webiny - Unified API for all Webiny functionality
• @webiny/cognito - Default authentication (replaceable)
• @webiny/cli - Development and deployment tools

Public/

Static assets for the Admin application:

• favicon.ico - Browser icon
• global.css - Global styles applied to Admin
• index.html - Admin app entry point
• robots.txt - SEO configuration

Customize these files to brand your Admin interface.

Configuration Files

tsconfig.json

• TypeScript compiler configuration
• Ensures type safety across all extensions
• Pre-configured for Webiny patterns

eslint.config.js

• Code linting rules
• Enforces consistent code style
• Includes Webiny-specific rules

webiny-env.d.ts

• TypeScript type definitions
• Environment-specific types
• Auto-generated, don’t edit directly

Project Organization

Single Package

Webiny uses a single-package approach:

• One package.json at the root
• All dependencies managed centrally
• No complex monorepo setup

Extension-Based Architecture

All customization through extensions:

• Clear separation of custom vs. framework code
• Extensions are portable and testable
• Easy to understand what’s custom

Deployment Artifacts

Build outputs are not stored in the project:

• Lambda functions built on deployment
• Admin app bundled during deployment
• Infrastructure state managed by Pulumi

Best Practices

Extension Organization

Group related functionality:

Naming Conventions

• Extensions - PascalCase (e.g., ProductApi.ts)
• Folders - camelCase or kebab-case
• Config files - Match tool conventions

Version Control

Track these files:

• Everything in extensions/
• webiny.config.tsx
• package.json and lock files
• Configuration files

Ignore:

• node_modules/
• Build outputs
• Environment-specific files

Next Steps

With an understanding of project structure:

• Learn about the Extension System
• Set up Local Development
• Explore TypeScript patterns