# How to Use the forc template Command for Sway Project Scaffolding

> Learn to use the forc template command to scaffold new Sway projects. This tool clones Git repos, extracts files, and updates manifest data for your project.

- Repository: [Fuel Labs/sway](https://github.com/FuelLabs/sway)
- Tags: how-to-guide
- Published: 2026-03-04

---

**The `forc template` command scaffolds new Sway projects by cloning a Git repository, extracting template files, and automatically rewriting manifest metadata to match your new project name.**

The `forc template` command in the FuelLabs/sway repository provides deterministic project scaffolding for the Sway smart contract language. This tool fetches templates from remote Git repositories or local examples, validates project identifiers, and prepares ready-to-compile project structures with updated [`Forc.toml`](https://github.com/FuelLabs/sway/blob/main/Forc.toml) configurations.

## How the forc template Command Works

The implementation in [`forc/src/ops/forc_template.rs`](https://github.com/FuelLabs/sway/blob/main/forc/src/ops/forc_template.rs) follows a rigorous seven-step pipeline to ensure reliable project generation.

### 1. Project Name Validation

First, `forc_template::init` validates the supplied `project_name` using `forc_util::validate_project_name` to ensure it conforms to legal Rust/Sway identifier standards. This check occurs before any network operations or file system mutations.

### 2. Repository Source Preparation

The command constructs a `source::git::Source` struct pointing to the repository HEAD specified by the `--url` flag. If `--template_name` is omitted, a temporary folder name is derived from the project name using the format `"{project_name}-template-source"`. The system generates a unique `fetch_id` based on the current directory and timestamp to manage temporary clones deterministically.

### 3. Git Fetch and Pinning

Using `source::git::pin` and `source::git::fetch` implemented in [`forc_pkg/src/source/git.rs`](https://github.com/FuelLabs/sway/blob/main/forc_pkg/src/source/git.rs), the tool creates a pinned reference to the remote repository and clones it into a temporary directory if not already cached locally.

### 4. Template Directory Selection

When `--template_name` is specified, `manifest::find_dir_within` searches the cloned repository for a subdirectory matching the provided name. If the template is not found, the command returns an error. If no template name is provided, the command expects a valid [`Forc.toml`](https://github.com/FuelLabs/sway/blob/main/Forc.toml) at the repository root and verifies this by attempting to parse the manifest.

### 5. File Copying

The selected template directory is copied to the target location using `fs_extra::dir::copy` with the `copy_inside = true` option, ensuring all template files transfer recursively into `current_dir/project_name`.

### 6. Manifest Mutation

The `edit_forc_toml` function rewrites the copied [`Forc.toml`](https://github.com/FuelLabs/sway/blob/main/Forc.toml) to inject the new project name, add the invoking user (retrieved via `whoami::realname()`) to the `authors` list, and remove explicit `std` dependencies that may conflict with the toolchain defaults. If a `test/` directory exists, `edit_cargo_toml` performs analogous updates to the test's [`Cargo.toml`](https://github.com/FuelLabs/sway/blob/main/Cargo.toml).

### 7. Completion

On success, the command returns `Ok(())`, leaving a fully configured Sway project in `./<project_name>`. The `println_action_green` utility provides colored feedback for each major step.

## forc template Command Examples

### Scaffold from a Remote Template Repository

To create a new project from a custom template repository:

```bash
forc template \
  --url https://github.com/owner/template-repo \
  --project_name my_new_project

```

This fetches the HEAD of the remote repository, locates the root [`Forc.toml`](https://github.com/FuelLabs/sway/blob/main/Forc.toml), and copies the entire repository structure into `./my_new_project` with updated metadata.

### Scaffold from a Built-in Sway Example

To scaffold from a specific example within the official sway repository:

```bash
forc template \
  --url https://github.com/FuelLabs/sway \
  --template_name counter \
  --project_name my_counter_app

```

The command locates the `counter` example under `examples/counter` using `manifest::find_dir_within`, copies it to `./my_counter_app`, and customizes the manifest files accordingly.

### Implementation Logic

The underlying Rust implementation follows this structure:

```rust
// Inside `forc_template::init`
validate_project_name(&command.project_name)?;
let source = source::git::Source {
    repo: Url::from_str(&command.url)?,
    reference: source::git::Reference::DefaultBranch,
};
// Clone / fetch if needed …
let repo_path = source::git::commit_path(...);
let from_path = match command.template_name {
    Some(name) => manifest::find_dir_within(&repo_path, name)
        .ok_or_else(|| anyhow!("template `{}` not found", name))?,
    None => repo_path, // expect a Forc.toml at root
};
// Copy and edit manifests …
copy_template_to_target(&from_path, &target_dir)?;
edit_forc_toml(&target_dir, &command.project_name, &whoami::realname())?;

```

This mirrors the actual implementation found in [`forc/src/ops/forc_template.rs`](https://github.com/FuelLabs/sway/blob/main/forc/src/ops/forc_template.rs).

## Core Implementation Details

Understanding the architecture helps when debugging or extending template functionality.

| Component | Source File | Function |
|-----------|-------------|----------|
| **CLI Parsing** | [`forc/src/cli.rs`](https://github.com/FuelLabs/sway/blob/main/forc/src/cli.rs) | Defines `TemplateCommand` with `--url`, `--template_name`, and `--project_name` flags |
| **Git Operations** | [`forc_pkg/src/source/git.rs`](https://github.com/FuelLabs/sway/blob/main/forc_pkg/src/source/git.rs) | Handles `source::git::pin` and `source::git::fetch` for deterministic cloning |
| **Template Discovery** | [`forc_pkg/src/manifest.rs`](https://github.com/FuelLabs/sway/blob/main/forc_pkg/src/manifest.rs) | Implements `manifest::find_dir_within` for subdirectory searching |
| **Manifest Editing** | [`forc/src/ops/forc_template.rs`](https://github.com/FuelLabs/sway/blob/main/forc/src/ops/forc_template.rs) | Contains `edit_forc_toml` and `edit_cargo_toml` for metadata updates |
| **User Feedback** | [`forc/src/ops/forc_template.rs`](https://github.com/FuelLabs/sway/blob/main/forc/src/ops/forc_template.rs) | Uses `println_action_green` for colored console output |

## Summary

- The `forc template` command clones Git repositories using deterministic fetch IDs based on directory paths and timestamps to avoid redundant downloads.
- Project names undergo strict validation via `forc_util::validate_project_name` to ensure compatibility with Sway identifiers.
- Template selection supports both root-level projects and named subdirectories within repositories via `manifest::find_dir_within`.
- Manifest files are automatically updated to reflect the new project name and authorship while removing conflicting `std` dependencies.
- The implementation relies on `fs_extra::dir::copy` for reliable cross-platform file operations.

## Frequently Asked Questions

### What happens if the template_name is not found in the repository?

According to the implementation in [`forc/src/ops/forc_template.rs`](https://github.com/FuelLabs/sway/blob/main/forc/src/ops/forc_template.rs), if `--template_name` is specified but `manifest::find_dir_within` cannot locate a matching directory in the cloned repository, the command returns an error indicating that the template was not found.

### How does forc template validate project names?

The command uses `forc_util::validate_project_name` at the beginning of the `forc_template::init` function to verify that the supplied `project_name` is a legal Rust/Sway identifier before proceeding with any Git operations or file copying.

### Why does forc template modify the authors field in Forc.toml?

The `edit_forc_toml` function automatically injects the invoking user's name (retrieved via `whoami::realname()`) into the `authors` field if not already present. This personalizes the new project while preserving other template metadata such as dependencies and entry points.

### What Git reference does forc template use when cloning repositories?

As implemented in [`forc_pkg/src/source/git.rs`](https://github.com/FuelLabs/sway/blob/main/forc_pkg/src/source/git.rs), the command uses `Reference::DefaultBranch` to pin and fetch the HEAD of the default branch from the specified URL. This ensures you receive the latest stable version of the template without specifying a particular tag or commit hash.