AgileBuilder logoAgileBuilder
Back to docs

Create Your First Template

Turn an ordinary project into an AgileBuilder template — add .agilebuilder.config.yaml, define variables and prompts, verify locally, then publish it as a Git repository your team can reuse.

An AgileBuilder template is just an ordinary Git repository plus one config file: .agilebuilder.config.yaml. There is no new project structure to learn — turning a working project into a template usually takes three steps: extract variables, write the config, and verify.

This tutorial turns a minimal Node.js service into a template.

Step 0: Start with a Working Project

Suppose you have a service skeleton that runs as-is:

my-service/
├── package.json
├── README.md
└── src/
    └── index.js

package.json:

{
  "name": "my-service",
  "version": "1.0.0",
  "main": "src/index.js"
}

Step 1: Replace Hard-Coded Values with Variables

AgileBuilder renders file contents with EJS. The default delimiter is %, so placeholders look like <%= variableName %>. Turn the name in package.json into a variable:

{
  "name": "<%= appName %>",
  "version": "1.0.0",
  "main": "src/index.js"
}

In the README you can combine variables with the built-in helpers:

# <%= pascalCase(appName) %>

A service generated with AgileBuilder.

File paths support variables too, using the {{variableName}} notation. Rename src/index.js to src/{{appName}}.js, and the path is rendered with the variable value at generation time. See Template Syntax for details.

Step 2: Write .agilebuilder.config.yaml

Create .agilebuilder.config.yaml at the repository root:

version: '1.0'
name: my-service-template
description: A minimal Node.js service template
variables:
  enabled: true
  delimiter: "%"
  filePatterns:
    mode: all
    patterns:
      - "**/*"
  inquirerQuestions:
    - name: appName
      type: input
      message: Application name
      required: true
      default: my-app

Key points:

  • Variable rendering (including file-path rendering) only happens when variables.enabled: true; it defaults to false.
  • filePatterns.mode: all renders every non-binary file; switch to include / exclude for precise control — see File Patterns and Hooks.
  • inquirerQuestions defines the interactive prompts. Generation fails with TEMPLATE_VARS_MISSING when a required: true variable is missing, and default fills in whatever is still missing.

The full schema is documented in Template Config Reference.

If the config file is missing, the CLI continues with the default config (no variable rendering, no hooks) and prints a warning — so a real template should always ship this file.

Step 3: Verify Locally

ag create clones templates from a Git URL, so first turn the template directory into a Git repository and commit:

cd my-service
git init
git add .
git commit -m "feat: make it an AgileBuilder template"

Then verify the output using the local path as --git-url:

ag create --git-url ./my-service --target ./out \
  --var appName=order-service

Inspect ./out: the name in package.json should be order-service, and src/index.js should have been rendered to src/order-service.js.

Try interactive mode once to see inquirerQuestions in action:

ag create --git-url ./my-service --target ./out2 --interactive

You can also register the template as a local resource before creating — closer to how a team actually uses it:

ag res add template --name my-service --git-url /absolute/path/to/my-service
ag res list
ag create 1 --target ./out3 --var appName=payment-service

Step 4: Publish to Your Team

Push the template repository to your team's Git hosting (GitHub, GitLab, or self-hosted Git). Each member then registers it:

git remote add origin https://github.com/your-org/my-service-template.git
git push -u origin main

# On each team member's machine:
ag res add template \
  --name my-service \
  --git-url https://github.com/your-org/my-service-template.git \
  --branch main
ag create <resource-id> --target ./new-service

After logging in, you can also register the template in a Cloud workspace so the whole team shares one resource list instead of registering it repeatedly:

ag space use <space-id>
ag res add template --name my-service --git-url https://github.com/your-org/my-service-template.git

What's Next