LEARN5 MIN READ · MARKDOWN ↗

Your first microapp

Create an Astro shell with a React microapp and check your first mount using CLI 1.2.0.

What you will achieve

You will open a page with a React application and test its counter. WU will display that application inside the page. We call this mounting a microapp or microfrontend.

The page hosting it is the shell. This walkthrough uses Astro for the shell and React for the microapp; you can choose other frameworks for your projects.

The folder containing both is a workspace. You will create it with the CLI, the terminal’s wu command. The CLI prepares files and runs development tools; the wu-framework package is the runtime that mounts apps in the browser.

1. Prepare the environment

Use Node 24 with npm. Open a terminal in the folder where you want to create the project and check your Node version:

node --version
npm --version

The first command should print v24.x.x. Install this walkthrough’s CLI and check its version:

npm install --global @wu-framework/cli@1.2.0
wu --version

The final command should print wu 1.2.0. If wu is not found or you use another Node version, see Installation and versions before continuing.

2. Create the shell and React

The mi-plataforma directory must not exist yet. Run:

wu create mi-plataforma --template react --shell astro
cd mi-plataforma

The command generates the Astro shell and a React microapp. These are the pieces you will use:

mi-plataforma/
├── shell/                 # Página anfitriona Astro
├── mf-mi-plataforma/      # Microapp React
├── wu.config.json         # Configuración del workspace
└── package.json

The app is named mi-plataforma; its folder has the mf- prefix. Run subsequent commands from this root, where wu.config.json is located. The necessary configuration is already generated.

3. Install and start

Install dependencies and wait for successful completion:

wu install

Then start the server and leave the terminal open:

wu dev --native --port 3000 --no-open

When the terminal announces it is listening, open http://127.0.0.1:3000. In this mode, WU serves the shell and microapp on port 3000. The first startup also builds the Astro shell, so it may take longer.

4. Check your first app

The CLI 1.2.0 template includes an initial screen and a counter:

On opening the page, look for Overview, Welcome to WU, and the mi-plataforma app.
Click mi-plataforma in navigation or its card. You should see React, the name mi-plataforma, and a counter under Interactions.
Click +: the value changes from 0 to 1. Click − to return to 0.
Click Overview to return to the initial screen.

You have mounted a microapp with WU. Seeing its name in navigation confirms registration; seeing the component and using its counter confirms it loaded and responds.

The React component you just used is in mf-mi-plataforma/src/App.tsx. The host page is in shell/src/pages/index.astro.

If something does not appear

What happens	What to review
Port 3000 is occupied	Stop the other server or choose another port with `--port`; open the URL with that number.
`wu install` ends with an error	Resolve the first terminal error before starting the server. See Diagnostics.
The page returns 404	Check whether the initial Astro build failed. WU listening does not guarantee the shell was built.
The shell opens but React remains blank	Inspect the browser’s first console or JavaScript-loading error. Continue with Development and reload.

More on versions, dependencies, and development mode

This recipe uses WU CLI 1.2.0 and Node 24. Project dependencies are resolved when you install them; the CLI version does not pin them. See Versions and distribution for the versions covered by this documentation.

wu install combines shell and app dependencies, preserves custom root scripts and metadata, and runs the configured package manager. Declare each dependency in the package that uses it. See dependencies and catalogs for shared ranges, conflicts and catalogs.

With --native, Astro builds the shell in shell/dist/; WU serves that output and rebuilds when sources change. This recipe does not start another Astro development server. Per-app ports in wu.config.json belong to the alternative --vite mode; microapp compilation still uses Node tools. Compare both modes.

The difference between wu.config.json, wu.json, and wu.init() is explained in What each file configures.

Next step

Continue with Adding a second app: keep this project and mount a Vue app alongside React.

If one app is enough for now, go directly to Preparing production to build and check its output.