Documentation
Playground

whitehall init

Create a new Whitehall project with all necessary files and configuration.

Usage

whitehall init <name>

Example

whitehall init myapp
cd myapp
whitehall run

What It Creates

The init command scaffolds a complete Whitehall project:

myapp/
├── whitehall.toml          # Project configuration
├── .env                    # Environment variables
├── .gitignore              # Git ignore patterns
├── src/
│   ├── main.wh             # App entry point
│   ├── routes/
│   │   ├── +screen.wh      # Home screen
│   │   └── +layout.wh      # Root layout
│   ├── components/         # Reusable components
│   ├── stores/             # ViewModels
│   ├── models/             # Data classes
│   └── lib/                # Utility functions
├── static/
│   └── icon.png            # App icon
└── build/                  # Generated files (gitignored)

Generated Files

whitehall.toml

Project configuration with sensible defaults:

[project]
name = "myapp"
version = "0.1.0"

[android]
package = "com.example.myapp"
min_sdk = 24
target_sdk = 34

[toolchain]
java = "21"
gradle = "8.4"
kotlin = "2.0.0"

src/main.wh

Application entry point:

@Composable
fun App() {
  <Router />
}

src/routes/+screen.wh

Default home screen:

<Column fillMaxSize p={20} gap={16}>
  <Text fontSize={24} fontWeight="bold">
    Welcome to Whitehall!
  </Text>

  <Text>
    Edit src/routes/+screen.wh to get started.
  </Text>
</Column>

src/routes/+layout.wh

Root layout wrapper:

<Scaffold>
  <TopAppBar title="MyApp" />
  <slot />
</Scaffold>

Next Steps

After creating your project:

1. Run on Device

cd myapp
whitehall run

2. Edit Files

Open src/routes/+screen.wh and start building your UI.

3. Add Dependencies

whitehall add io.coil-kt/coil-compose

4. Enable Watch Mode

whitehall build --watch

Configuration Options

Customize whitehall.toml after creation:

Package Name

[android]
package = "com.mycompany.myapp"

SDK Versions

[android]
min_sdk = 26    # Minimum Android version
target_sdk = 34 # Target Android version

Dependencies

[dependencies]
"io.coil-kt/coil-compose" = "2.6.0"
"com.squareup.okhttp3/okhttp" = "4.12.0"

App Icons

[android.icons]
default = "static/icon-default.png"
dark = "static/icon-dark.png"

Templates

Future versions will support templates:

whitehall init myapp --template navigation
whitehall init myapp --template social
whitehall init myapp --template ecommerce

Whitehall automatically manages Java, Gradle, and Android SDK. Run whitehall doctor to verify your setup.

Environment Variables

The generated .env file contains example environment variables:

API_URL=https://api.example.com
DEBUG=true

Access them in your code:

val apiUrl = $env.API_URL

Version Control

The generated .gitignore excludes build artifacts and secrets:

build/
.env.local
*.apk
*.aab

Troubleshooting

Project Already Exists

If the directory exists, choose a different name or remove the existing directory:

rm -rf myapp
whitehall init myapp

Permission Denied

Ensure you have write permissions in the current directory:

ls -la .

See Also