Core Concepts

Project Structure

Understanding the organization of a Webiny project.

WHAT YOU'LL LEARN

- How Webiny projects are organized - The purpose of each file and folder - Where to place custom code

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

webiny.config.tsx

`/extensions`

The workspace for all custom code. You can organize this folder however you like. There are four types of extensions you can create:

API Extensions - Add GraphQL schemas, custom business logic, lifecycle hooks
Admin Extensions - Customize the Admin UI with themes, white-label branding, custom views
Infrastructure Extensions - Modify Pulumi infrastructure code
CLI Extensions - Create custom CLI commands for your workflows

Learn More About Extensions

For detailed information about the extension system, how to create extensions, and examples, see the Extensions documentation.

Example organization:

Reference extensions in webiny.config.tsx:

webiny.config.tsx

`package.json`

Contains project dependencies with key Webiny packages:

package.json

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

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