# Creating a project

Interactive mode, reproducible scaffolding, Astro shell, and generated TypeScript.

See versions, changes and requirements in [Framework 4.0 and CLI 1.2](/docs/guides/releases/).


<span id="creación-reproducible"></span>

<span class="section-anchor" id="section-1"></span>

## Reproducible creation

```bash
wu create conocimiento --template react --shell astro
```

Quick mode activates when a name and template are provided. It writes `conocimiento/`, an Astro shell, a React microapp named `conocimiento`, configuration, and manifests. **This mode does not install dependencies.** At the end it suggests entering the folder and running `wu install` and `wu dev`.

```text
conocimiento/
  .gitignore
  package.json
  wu.config.json
  shell/
    package.json
    astro.config.mjs
    src/pages/index.astro
    src/styles/wu-shell.css
  mf-conocimiento/
    package.json
    index.html
    vite.config.js
    src/main.tsx
    src/App.tsx
```

The structure shows the main files for that combination. Other frameworks choose different extensions, components, and configurations. The generator does not write a source `wu.json`: the development server can synthesize one, and the build writes the production manifest. Create one explicitly when the app needs to declare contracts or permissions.

A new project includes `.gitignore` for dependencies, builds, caches, logs, PEM keys and `.env`, retaining `.env.example`. `wu upgrade` can add those rules to an older project without replacing existing ones.

<span id="opciones-reconocidas"></span>

<span class="section-anchor" id="section-2"></span>

## Recognized options

| Argument | Alias | Effect |
| --- | --- | --- |
| Positional name | — | Project directory and first app name in quick mode |
| `--template <framework>` | `-t` | Generated microapp framework |
| `--shell <framework>` | `-s` | Shell framework in quick mode |

If you omit `--shell`, the shell uses the `--template` selection; its actual form may be a framework-specific or framework-agnostic shell. `--shell` without `--template` does not configure the wizard: the interactive flow asks for the shell again.

There is no `--no-install` for `create`, because quick mode already leaves installation pending. There are also no public `--typescript`, `--yes`, `--package-manager`, or `--apps` flags. Use only the contract in the table to automate this version.

<span id="asistente-interactivo"></span>

<span class="section-anchor" id="section-3"></span>

## Interactive wizard

```bash
wu create
```

The wizard uses raw terminal mode. It requests a name, shell, and microapps one by one; it offers TypeScript where the template supports it. App ports start at 5001 and increment. The interactive flow supports up to 16 apps; use explicit configuration for larger topologies.

The wizard asks to confirm generation and installation and runs `wu install`. A failed installation returns `1`; without a terminal it also returns `1` and shows quick mode. Ctrl+C cancels with `130`. Quick mode still does not install dependencies.

<span id="nombres-y-validaciones"></span>

<span class="section-anchor" id="section-4"></span>

## Names and validation

Creation rejects an existing directory with exit code 1. An unknown template also fails. Astro and Next are in the shell catalog but are rejected as the `--template` for a microapp.

App names are normalized and validated against `^[a-z][a-z0-9-]{0,31}$`, excluding Windows reserved names. The project allows up to 64 characters without paths or spaces; the first app in quick mode must also meet its 32-character limit. A generation failure leaves no partial directory.

<span id="astro-dentro-del-proyecto-wu"></span>

<span class="section-anchor" id="section-5"></span>

## Astro inside a WU project

Astro compiles the shell with its own bundler. WU serves that output and mounts microapps from their WU entrypoints. The scaffold does not turn React or Vue into Astro islands: composition between applications belongs to the WU runtime.

The generated shell imports its stylesheet, initializes the framework, and consumes the app catalog inserted by the CLI. Configuration declares `npx astro dev` and `npx astro build`. In native development mode, WU uses Astro's build output and rebuilds it when its sources change.

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-6"></span>

## Implementation references

- `wu-cli/src/commands/create.zig`
- `wu-cli/src/config/names.zig`
- `wu-cli/src/config/catalog.zig`
- `wu-cli/src/commands/templates/astro-shell.index.astro`
- `wu-cli/tests/create-exit-code.test.cjs`
- `wu-cli/tests/wizard-keys.test.cjs`
- `wu-cli/tests/gitignore.test.cjs`