This document demonstrates how to add components directly to the component
instance tree during development and interact with them at runtime.

Fuchsia provides a few abstractions on top of


[](https://fuchsia.dev/docs/glossary#component-framework)


for specific use cases. If you are building components using one of the
following frameworks, refer to the corresponding guides instead:

- **Session components:** [Building and running a session](https://fuchsia.dev/docs/development/sessions/building-and-running-a-session)
- **Test components:** [Run Fuchsia tests](https://fuchsia.dev/docs/development/testing/run_fuchsia_tests)

> [!NOTE]
> **Note:** For more details on the commands described in this guide, see the [`ffx component` reference](https://fuchsia.dev/reference/tools/sdk/ffx.md#component).

## Concepts

You should understand the following concepts before running a component:

- At runtime, the [](https://fuchsia.dev/docs/glossary#component-instance-tree) connects individual [](https://fuchsia.dev/docs/glossary#component-instance) together in a hierarchy of parent and child relationships.
- Component instances progress through four major lifecycle states: create, start, stop, and destroy.
- A [](https://fuchsia.dev/docs/glossary#moniker) identifies component instances within the tree using their topological path.
- Component instances are declared **statically** as a [child](https://fuchsia.dev/reference/cml#children) of another component in their [](https://fuchsia.dev/docs/glossary#component-manifest) or created **dynamically** at runtime in a [component collection](https://fuchsia.dev/reference/cml#collections). Each instance consists of a component `name` and `url`.
- A [](https://fuchsia.dev/docs/glossary#component-url) identifies a component. Component URLs are resolved by the component framework, often to a resource inside a package.

For more details on component execution, see
[Component lifecycle](https://fuchsia.dev/docs/concepts/components/v2/lifecycle).

## Component instances

The first step to running a component is adding a new component instance to the
tree. The position of the component instance within the tree determines its
available


[](https://fuchsia.dev/docs/glossary#capability)


.

### Discover static components

Static components are *declared* as children of another component instance in
the tree. You can use `ffx component show` to determine the moniker and
component URL of a static component instance:

    ffx component show COMPONENT_NAME

Replace `COMPONENT_NAME` with the name of a component. The following example
shows the command output for the `pkg-resolver` component:

    $ ffx component show pkg-resolver
                   Moniker: /core/pkg-resolver
                       URL: fuchsia-pkg://fuchsia.com/pkg-resolver#meta/pkg-resolver.cm
                      Type: CML static component
           Component State: Resolved
           Execution State: Running
    ...

Static component instances cannot be created or destroyed at runtime.

### Manage dynamic components

Dynamic components are *created* at runtime inside of a collection. You can use
`ffx component create` to create a new component instance, providing a target
moniker within an existing collection and a component URL for resolving the
component:

    ffx component create TARGET_MONIKER COMPONENT_URL

Replace `TARGET_MONIKER` with the destination moniker of the new component
inside an existing collection and `COMPONENT_URL` with the location where the
component is being served. For example, the following command creates a new
component instance named `hello-world` inside the `ffx-laboratory` collection:

    $ ffx component create /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
    URL: fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
    Moniker: /core/ffx-laboratory:hello-world
    Creating component instance...

Similarly, use `ffx component destroy` to destroy a dynamic component instance
by providing its moniker:

    ffx component destroy TARGET_MONIKER

Replace `TARGET_MONIKER` with the moniker of the component to destroy. The
following example destroys the `hello-world` component created above:

    $ ffx component destroy /core/ffx-laboratory:hello-world
    Moniker: /core/ffx-laboratory:hello-world
    Destroying component instance...

## Component execution

Once a component instance exists in the tree, you can start and stop the target
instance using `ffx component`.

### Start the instance

Use `ffx component start` to explicitly start a component instance:

    ffx component start TARGET_MONIKER

Replace `TARGET_MONIKER` with the moniker of the component to start. The
following example starts the `hello-world` component created previously:

    $ ffx component start /core/ffx-laboratory:hello-world
    Moniker: /core/ffx-laboratory:hello-world
    Starting component instance...

### Stop the instance

Use `ffx component stop` to terminate execution of a running component instance
using its moniker:

    ffx component stop TARGET_MONIKER

Replace `TARGET_MONIKER` with the moniker of the component to stop. The
following example stops to the `hello-world` component started above:

    $ ffx component stop /core/ffx-laboratory:hello-world
    Moniker: /core/ffx-laboratory:hello-world
    Stopping component instance...

> [!NOTE]
> **Note:** You can add the `--recursive` flag to stop all child components. For more details, see the [`ffx component` reference](https://fuchsia.dev/reference/tools/sdk/ffx.md#component).

### Run a component

The `ffx component run` command provides a quickstart to run basic components
during development. It is a shortcut for `ffx component create` followed by
`ffx component start`:

    ffx component run TARGET_MONIKER COMPONENT_URL

Replace `TARGET_MONIKER` with the destination moniker of the new component
inside an existing collection and `COMPONENT_URL` with the location where the
component is being served. For example, the following command creates a new
component instance named `hello-world-rust` inside the `ffx-laboratory`
collection:

    $ ffx component run /core/ffx-laboratory:hello-world-rust fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
    URL: fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
    Moniker: /core/ffx-laboratory:hello-world-rust
    Creating component instance...
    Starting component instance...

The example above is equivalent to running the following individual `ffx`
commands:

    $ ffx component create /core/ffx-laboratory:hello-world-rust fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
    $ ffx component start /core/ffx-laboratory:hello-world-rust

# Ways to update a component

When you make changes to your component, you'll often want to update one of its
instances running on the device. For example, you may change the component's
binary, and restart the component to run with the new binary. Or you may change
its manifest to add new capability routes and want to make those capability
routes available on the device.

The `ffx component reload` command is the fastest and most complete way to
reload a component. But it's not the only way and understanding the other
methods may allow more precise operations for special use cases.

The methods are summarized here and explained in full below.

### Summary

| Command | Description | Updates package | Updates manifest | Preserves resources |
|---|---|---|---|---|
| ffx component reload | stops, updates, and starts | yes | yes | yes |
| ffx component destroy/create/start | destroys, then starts | yes | yes | no |
| ffx component run --recreate | destroys, then starts | yes | yes | no |
| ffx component stop/start | stops and starts without destroying | no | no | yes |

> - "Updates package" means that the code is updated when the package is reloaded.
> - "Updates manifest" means that the manifest cache is reloaded, updating the routing and other information contained in the FIDL files.
> - "Preserves resources" means that resources such as storage that would be released by a destroy command are instead preserved.

### Reload

Update your component's code and manifest while retaining resources with:

    ffx component reload TARGET_MONIKER

This command will first shut down the component, then reload and restart it. The
command updates the package and manifest without destroying the component or
releasing resources.

The `reload` command preserves your component's resources such as storage. This
preservation can be helpful if it is slow to initialize, acquire, or recreate
resources in a specific state for debugging.

Reloading is also faster when destroying the component is expensive, such as
when it requires shutting down and restarting a session or the target
device/emulator.

### Destroy/create/start

To fully reload the component and drop acquired resources, you can first destroy
the existing component instance, then restart it. Use:

    $ ffx component destroy TARGET_MONIKER
    $ ffx component create TARGET_MONIKER COMPONENT_URL
    $ ffx component start TARGET_MONIKER

This sequence will reload both the package and the manifest, so code and
capability changes will be updated. However, destroying the component will also
free any resources it uses. This full reset may be what you want if your goal is
to start with a completely reinitialized component.

### Run --recreate

A convenient command that is analogous to the destroy/create/start sequence is
the `run` command with `--recreate`:

    ffx component run TARGET_MONIKER COMPONENT_URL --recreate

### Stop/start

Although it's not primarily a way to do updates, a side effect of just stopping,
then starting your component is that it will be partially updated.

    $ ffx component stop TARGET_MONIKER
    $ ffx component start TARGET_MONIKER

Assuming a package manager such as `ffx serve` is running, the latest version of
the component's code will be loaded and run. However, due to the way caching
works in the Fuchsia component framework, the manifest will not be updated. The
manifest contains your component's routing and other information as defined in
the `*.cm` files. So if you change your component's capability routes, stopping
and starting the component will not pick up these changes.

## `ffx-laboratory`

The `ffx-laboratory` is a component collection that provides a restricted set of
capabilities for development. The following capabilities are offered to
components in this collection:

- [Protocol capabilities](https://fuchsia.dev/docs/concepts/components/v2/capabilities/protocol)
  - [`fuchsia.logger.LogSink`](https://fuchsia.dev/reference/fidl/fuchsia.logger#LogSink): Record log messages. You can use this protocol with `include: [ "syslog/client.shard.cml" ],` in your component's CML file.
  - [`fuchsia.process.Launcher`](https://fuchsia.dev/reference/fidl/fuchsia.process#Launcher): Create new processes
- [Storage capabilities](https://fuchsia.dev/docs/concepts/components/v2/capabilities/storage)
  - `tmp`: Temporary storage (non-persistent)
  - `data`: Emulated persistent storage backed by `/tmp`
  - `cache`: Emulated cache storage backed by `/tmp`
- [Directory capabilities](https://fuchsia.dev/docs/concepts/components/v2/capabilities/directory)
  - `/boot`: Read-only `bootfs` provided by Component Manager

The `ffx-laboratory` is a [`transient`](https://fuchsia.dev/reference/cml#collections) collection.
Component instances in this collection will persist even after they stop. To
destroy a component instance in this collection, use the `ffx component destroy`
command.

## Troubleshooting

This section contains common issues you may encounter while running your
components during development.

### Unable to resolve the component

When using `ffx component start` or `ffx component run` you may encounter the
following error if component framework cannot resolve the component instance:

    $ ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
    URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
    Moniker: /core/ffx-laboratory:hello-world
    Creating component instance...
    Starting component instance...
    Lifecycle protocol could not bind to component instance: InstanceCannotResolve

This occurs when the component URL does not resolve to a valid component
manifest.

To address this issue, verify the following:

- The [component URL](https://fuchsia.dev/docs/reference/components/url) is formatted correctly.
- You have a [package server running](https://fuchsia.dev/docs/development/build/package_update#connecting_host_and_target).
- Your package server is registered with the target.
- Your [component is published](https://fuchsia.dev/docs/development/build/package_update#triggering_package_updates) to the package server.

### Component instance already exists

When using `ffx component create` or `ffx component run` you may encounter the
following error if the component instance already exists:

    $ ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
    URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
    Moniker: /core/ffx-laboratory:hello-world
    Creating component instance...
    Component instance already exists. Use --recreate to destroy and recreate a new instance, or --name to create a new instance with a different name.

This occurs when the target moniker is already in use by another component
instance.

To address this issue, manually destroy the instance using the `ffx component
destroy` command:

    $ ffx component destroy /core/ffx-laboratory:hello-world
    Moniker: /core/ffx-laboratory:hello-world
    Destroying component instance...

If you are using `ffx component run`, add the `--recreate` flag to destroy the
instance and recreate it:

    $ ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm --recreate
    URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
    Moniker: /core/ffx-laboratory:hello-world
    Creating component instance...
    Component instance already exists. Destroying...
    Recreating component instance...
    Starting component instance...

Alternatively, add the `--name` flag to create a new instance with a different
name:

    $ ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm --name hello-world-2
    URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
    Moniker: /core/ffx-laboratory:hello-world-2
    Creating component instance...
    Starting component instance...

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/components/run.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/components/run.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/components/run.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/components/run.md "Edit the source code of this page")