How to Use the forc template Command for Sway Project Scaffolding

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 configurations.

How the forc template Command Works

The implementation in 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, 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 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 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.

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:

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, 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:

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:

// 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.

Core Implementation Details

Understanding the architecture helps when debugging or extending template functionality.

Component	Source File	Function
CLI Parsing	forc/src/cli.rs	Defines TemplateCommand with --url, --template_name, and --project_name flags
Git Operations	forc_pkg/src/source/git.rs	Handles source::git::pin and source::git::fetch for deterministic cloning
Template Discovery	forc_pkg/src/manifest.rs	Implements manifest::find_dir_within for subdirectory searching
Manifest Editing	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	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, 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}