@commercetools-frontend/create-mc-app

Check out the documentation for more information.

Local Development

This guide is for internal developers who want to modify starter templates and test changes locally without publishing a new release.

How It Works

The CLI clones templates from the GitHub repository (not your local filesystem). This means you must push template changes to a git branch before testing them locally.

Prerequisites

• Repository cloned locally
• pnpm installed
• Git push access to the repository

Workflow

1. Make Template Changes

Edit files in the template directories:

# For custom applications
application-templates/starter/
application-templates/starter-typescript/

# For custom views
custom-views-templates/starter/
custom-views-templates/starter-typescript/

2. Commit and Push to a Branch

git checkout -b my-template-changes # create a new branch
git add application-templates/starter/ # do this after you make changes
git commit -m "chore(templates): add welcome header to starter template"
git push origin my-template-changes # push the changes to the new branch

3. Run the Local CLI with Your Branch

From the repository root:

NODE_ENV=test node packages/create-mc-app/bin/cli.js my-test-app \
  --template starter \
  --template-version my-template-changes # important: use the branch name you created

Important: Use relative paths (e.g., my-test-app) not absolute paths (e.g., /Users/name/my-test-app).

4. Verify Your Changes

cd my-test-app # navigate to the new app
yarn start # verify your template changes are present

Quick Reference

# Complete workflow
git checkout -b template-updates # create a new branch
# ... make changes to application-templates/starter/ (e.g., add a welcome message) ...
git add application-templates/starter/ # do this after you make changes
git commit -m "chore(templates): update landing page styles"
git push origin template-updates # push the changes to the new branch

cd packages/create-mc-app
pnpm build
cd ../..

NODE_ENV=test node packages/create-mc-app/bin/cli.js test-project \
  --template starter \
  --template-version template-updates

cd test-project # navigate to the new app
yarn start # verify your template changes are present

Key Points

• ✅ Must push changes to git - Templates are cloned from GitHub, not copied from local filesystem
• ✅ Use relative paths - Avoid absolute paths starting with /
• ✅ Use --template-version - Specify your branch name to test changes
• ✅ No npm publish needed - Test directly with git branches
• ✅ Test before merging - Validate template changes work correctly before merging to main

Troubleshooting

Error: "Name contains illegal characters"

• You're using an absolute path. Use a relative path instead (e.g., my-app instead of /Users/name/my-app)

Templates not reflecting changes

• Ensure you've pushed your changes to the git branch
• Verify the --template-version flag matches your branch name