# Start a component during development

For testing and debugging purposes, the
[`ffx component`](https://fuchsia.dev/reference/tools/sdk/ffx#component) commands can quickly
start a [dynamic component instance](https://fuchsia.dev/docs/concepts/components/v2/realms#dynamic-children) on a device.

## Concepts

Component instances on a device are usually declared using
[component manifests](https://fuchsia.dev/docs/concepts/components/v2/component_manifests), which statically define the topology
and capabilities of the components on the device. However, statically declaring
a component isn't the only way to create a component instance
on a device. You can also use the `ffx component` commands to create a dynamic
component instance on the device at runtime.

One important difference is that Fuchsia restricts all dynamic
component instances to run under a [component collection](https://fuchsia.dev/docs/concepts/components/v2/realms#collections).
A collection serves as a container for dynamic component instances.
Consequently, the capabilities of component instances
under a collection are limited by the capabilities that the collection is able
to expose and offer.

While a new component collection can be declared using a component manifest
(similar to declaring a static component instance), Fuchsia
provides a number of predefined collections for general usage.
For instance, [`ffx-laboratory`](https://fuchsia.dev/docs/development/components/run#ffx-laboratory) is one of those predefined
collections.

## Start a component

To create a new dynamic component instance, you first need to run
[`ffx component create`](https://fuchsia.dev/reference/tools/sdk/ffx#create_2) to add a new component
to the component instance tree on a device. Once added,
you can run [`ffx component start`](https://fuchsia.dev/reference/tools/sdk/ffx#start) to start the component
on the device.

To start a new dynamic component instance on a device, do the following:

1. Create a new component instance:

       ffx component create <TARGET_MONIKER> <COMPONENT_URL>

   Replace the following:
   - `TARGET_MONIKER`: The destination moniker of a new component instance. The moniker must include a component collection on the path.
   - `COMPONENT_URL`: The resource location of a component.

   The example below creates a new component instance for the
   `hello-world-cpp.cm` component and assigns its moniker to be
   `/core/ffx-laboratory:hello-world`:

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

   > [!NOTE]
   > **Note:** To remove this component instance from the tree, see [Destroy a component](https://fuchsia.dev/fuchsia-src/development/tools/ffx/workflows/start-a-component-during-development#destroy-a-component).

2. Start the component instance:

       ffx component start <TARGET_MONIKER>

   Replace `TARGET_MONIKER` with the moniker used in Step 1.

   The example below starts the component instance at
   `/core/ffx-laboratory:hello-world`:

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

   > [!NOTE]
   > **Note:** To stop this component instance, see [Stop a component](https://fuchsia.dev/fuchsia-src/development/tools/ffx/workflows/start-a-component-during-development#stop-a-component).

## Start a component under ffx-laboratory

Starting a dynamic component instance would normally require running a
sequence of the `ffx component create` and `ffx component start` commands
(see [Start a component](https://fuchsia.dev/fuchsia-src/development/tools/ffx/workflows/start-a-component-during-development#start-a-component)). However,
the [`ffx component run`](https://fuchsia.dev/reference/tools/sdk/ffx#run) command can start a dynamic
component instance in a single command line.

To quick start a component under the `ffx-laboratory` collection,
run the following command:

    ffx component run /core/ffx-laboratory:<NAME> <COMPONENT_URL>

Replace `COMPONENT_URL` with the resource location of a component, and replace
`NAME` with the name for the component instance within the `ffx-laboratory`
collection.

The example below starts the `hello-world-cpp.cm` component on the device:

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

In essence, the `ffx component run` command performs the following steps:

1. Run `ffx component create` to create a new component instance under the `ffx-laboratory` collection using the component name as the target moniker.
2. Run `ffx component start` to start the component instance on the device.

For instance, running `ffx component run /core/ffx-laboratory:hello-world-cpp fuchsia-pkg://fuchsia.com/hello-world-cpp#meta/hello-world-cpp.cm`
in the example above is equivalent to running the following commands:

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

## Stop a component

To stop a running component instance on a device, run the following command:

    ffx component stop <TARGET_MONIKER>

Replace `TARGET_MONIKER` with the moniker of a component instance.

The example below stops the component instance at
`/core/ffx-laboratory:hello-world`:

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

## Destroy a component

To remove a dynamic component instance from the component instance tree
on a device, run the following command:

    ffx component destroy <TARGET_MONIKER>

Replace `TARGET_MONIKER` with the moniker of a component instance.

The example below removes the component instance at
`/core/ffx-laboratory:hello-world`:

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

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