Project Structure

After running w3m new my-project --template token-standard (or any template with a frontend), the scaffolder generates the following structure:

my-project/
├── contracts/
│   ├── src/              # Solidity contracts
│   ├── test/             # Foundry tests
│   ├── script/           # Deploy scripts (e.g. Deploy.s.sol)
│   ├── foundry.toml      # Foundry configuration
│   └── remappings.txt    # Solidity import remappings
├── web/
│   ├── app/              # Next.js App Router pages and layouts
│   │   ├── layout.tsx    # Root layout with Providers wrapper
│   │   ├── page.tsx      # Home page
│   │   ├── providers.tsx # WagmiProvider + QueryClientProvider + KitProvider
│   │   └── globals.css   # Global styles (Tailwind CSS)
│   ├── lib/
│   │   └── wagmi.ts      # Wagmi config with chain transports
│   ├── next.config.ts    # Next.js configuration
│   ├── package.json      # Frontend dependencies
│   └── tsconfig.json     # Frontend TypeScript config
├── src/
│   └── generated/        # Auto-generated TypeScript bindings and hooks
├── deployments/          # Deployment addresses per chain (JSON)
├── kit.config.ts         # Project configuration
├── package.json          # Root workspace package.json
├── pnpm-workspace.yaml   # pnpm workspace definition
├── turbo.json            # Turborepo task configuration
├── biome.json            # Biome linter and formatter configuration
├── vercel.json           # Vercel deployment configuration
├── .env.example          # Template for required environment variables
├── .gitignore            # Git ignore rules
└── README.md             # Project readme

Directory Details

`contracts/`

The smart contract workspace. Follows the standard Foundry project layout.

contracts/src/ — Solidity source files. Template contracts are placed here during scaffolding, and module contracts are added when you run w3m add <component>. All contracts use OpenZeppelin Contracts v5.1.0.
contracts/test/ — Foundry test files. Run with forge test or w3m test.
contracts/script/ — Forge deployment scripts. Deploy.s.sol reads DEPLOYER_PRIVATE_KEY and deploys your contracts. Both w3m dev and w3m deploy execute this script.
contracts/foundry.toml — Foundry configuration (Solidity version, source/output directories, formatter settings).
contracts/remappings.txt — Maps import paths like @openzeppelin/ and forge-std/ to installed locations.

Foundry dependencies (OpenZeppelin, forge-std) are installed into contracts/lib/ via forge install. This directory is git-ignored.

`web/`

The frontend application workspace. With Next.js selected (the default), this is a Next.js 15 project using the App Router.

web/app/providers.tsx — Sets up the provider stack: WagmiProvider, QueryClientProvider, and KitProvider from @web3marketlabs/react.
web/app/layout.tsx — Root layout wrapping all pages with the Providers component.
web/lib/wagmi.ts — Wagmi configuration with chain transports.

When you select Vite + React, the web/ directory contains a standard Vite project. If you select “None” for the frontend, the web/ directory is not created.

`src/generated/`

Auto-generated TypeScript bindings and React hooks produced by the codegen pipeline. Populated by w3m generate (or automatically during w3m dev and w3m deploy).

The pipeline reads compiled ABIs from contracts/out/, deployment addresses from deployments/, and config from kit.config.ts to produce:

ABI TypeScript constants — typed ABI arrays for each contract
React hooks — contract-specific read/write hooks
Address maps — deployment addresses keyed by chain ID

⚠️

Do not edit files in src/generated/ manually. They are overwritten every time codegen runs.

`deployments/`

Deployment records stored as JSON files, one per chain (e.g. 11155111.json for Sepolia, 31337.json for local Anvil). Written by w3m deploy and by local deployment from the workspace menu. The codegen pipeline reads these to populate generated address maps.

`kit.config.ts`

The central configuration file. Uses defineConfig from @web3marketlabs/config and is validated against a Zod schema:

kit.config.ts

import { defineConfig } from '@web3marketlabs/config'
 
export default defineConfig({
  contracts: {
    framework: 'foundry',
    root: 'contracts',
  },
  chains: {
    default: 'sepolia',
  },
  codegen: {
    outDir: 'src/generated',
    hooks: true,
  },
  components: ['token'],
})

See the Configuration page for the full schema.

Root Configuration Files

package.json — Root workspace package with scripts delegating to the CLI.
pnpm-workspace.yaml — pnpm workspace packages (contracts and web). Only generated when pnpm is selected.
turbo.json — Turborepo task configuration.
biome.json — Biome linter/formatter configuration.
vercel.json — Vercel deployment config (generated when a frontend is selected).
.env.example — Template listing required environment variables.
.gitignore — Ignores node_modules/, build outputs, .env, Foundry artifacts, .turbo/, and src/generated/.

Quickstart Index