Downloads

Download ForgeBox box.json Template Library

by Aaron Longnion
8 min read
Contents show

Overview

The ForgeBox box.json Template Library is a curated set of professionally crafted starter manifests and snippets designed for CommandBox and CFML projects that publish to or depend on ForgeBox packages. Each template reflects common, proven patterns for ColdBox apps, modules, CLI commands, and libraries, so you can generate a clean, Standards-compliant box.json in minutes rather than piecing one together from scratch. This helps teams keep package metadata consistent, simplifies dependency management, and makes Automation in CI/CD far more reliable.

Whether you’re spinning up a new ColdBox module, preparing a private package for your organization, or polishing a reusable CLI command, these templates give you a sensible baseline and practical examples for fields, scripts, and versioning. Everything is organized, predictable, and aligned with current CommandBox and ForgeBox conventions.

What You’ll Get

  • A downloadable library (ZIP) of ready-to-use templates:
    • ColdBox app box.json
    • ColdBox module box.json
    • Generic CFML library box.json
    • CommandBox CLI command box.json
    • Private/internal package box.json
    • Minimal quick-start box.json
  • Commented examples and variations:
    • Fields for name, slug, version, description, authors, repository, license
    • dependencies and devDependencies examples
    • scripts examples (test, build, release)
    • distribution and packaging guidance (excludes, installPaths)
  • A quick-start PDF (8–12 pages):
  • JSON schema references and validation tips:
    • How to get IntelliSense/autocomplete in popular editors
    • Examples of valid vs. invalid structures
  • Integration snippets:
    • VS Code snippet suggestions for box.json scaffolding
    • Sample CI snippets for GitHub Actions, GitLab CI, and Azure Pipelines
  • A small set of real-world examples:
    • A ColdBox module ready to publish on ForgeBox
    • A private enterprise library with internal dependencies
    • A CLI command package with test and release scripts
See also  Download a ColdFusion Error Handler Template (ZIP)

Supported Environments and Requirements

  • CommandBox 5.x or later recommended (6.x fully supported)
  • CFML engines:
    • Lucee 5+ (common for ColdBox apps and modules)
    • Adobe ColdFusion 2018+ (depending on your project’s engine targets)
  • Git 2.3+ (optional but strongly recommended for versioning and CI)
  • Popular editors:
    • VS Code (with JSON schema validation and snippets)
    • Any editor capable of JSON validation

Notes:

  • If you publish to ForgeBox, you’ll need a ForgeBox account and API token configured in CommandBox.
  • Private/internal packages can be hosted in ForgeBox Pro or kept local. The library includes templates for both paths.

Benefits

  • Faster project setup: Create a high-quality box.json in less than a minute using proven templates.
  • Consistency across teams: Standardized fields, scripts, and dependency patterns reduce drift and merge noise.
  • Better DX and Automation: Clear scripts for test/build/release make local development and CI/CD simpler.
  • Fewer publishing errors: Correctly formed metadata and versioning patterns decrease registry and Install issues.
  • Improved discoverability: Thoughtful descriptions, keywords, and repository links help others find and use your packages on ForgeBox.

How to Install and Set Up

Option A: Download the ZIP

  1. Download the ZIP archive containing the ForgeBox box.json Template Library.
  2. Unzip it into a tools or templates folder in your workspace.
  3. Explore the folders (apps, modules, cli-commands, libraries, private-packages, minimal).
  4. Open a template and copy the contents into your project’s box.json.
  5. Replace placeholders (org, repo URL, description, version) with your project’s details.

Option B: Clone via Git (recommended for updates)

  1. Navigate to your workspace:
    • cd ~/dev/templates
  2. Clone the repository that contains the library:
    • git clone forgebox-boxjson-templates
  3. Pull updates occasionally:
    • cd forgebox-boxjson-templates
    • git pull

Option C: Reference locally as snippets (VS Code)

  1. Copy the snippets from the library’s vscode-snippets folder.
  2. In VS Code, open Command Palette → Preferences: Configure User Snippets → JSON.
  3. Paste the snippet definitions; adjust prefixes and descriptions if needed.
  4. Type the snippet prefix in box.json to insert your preferred template.

How to Use the Templates

Step 1: Pick the right template

  • ColdBox app: Choose the coldbox-app template if you’re scaffolding a full application.
  • ColdBox module: Use the module template to publish or share modular functionality.
  • CLI command: Select the cli-command template for custom CommandBox commands.
  • Library: Start with the cfml-library template if you’re creating a general CFML package.
  • Private: Begin with the private-package template if this stays internal.
See also  Download ColdFusion Health Check & Status Endpoint Example

Step 2: Customize core metadata

  • name and slug: Keep them short, lowercase, and unique. The slug is how your package is identified on ForgeBox.
  • version: Use semantic versioning (e.g., 1.2.0).
  • description and keywords: Make them informative to improve discoverability.
  • repository and bugs/homepage: Link back to your code and documentation.
  • license: Choose a clear license (e.g., MIT, Apache-2.0) or designate private.

Example minimal structure:
{
“name”: “awesome-coldbox-module”,
“slug”: “awesome-coldbox-module”,
“version”: “1.0.0”,
“type”: “module”,
“description”: “Adds awesome Features to ColdBox apps.”,
“keywords”: [“coldbox”, “module”, “cfml”],
“repository”: { “type”: “git”, “url”: “https://github.com/org/awesome-coldbox-module.git” },
“license”: “MIT”
}

Step 3: Add dependencies and devDependencies

  • dependencies: Packages required at runtime.
  • devDependencies: Tools used in development (e.g., TestBox).
  • Use version ranges wisely:
    • ^1.2.0 to accept non-breaking minor updates
    • ~1.2.3 to lock down patch updates
    • Exact pinning for reproducible builds

Example:
“dependencies”: {
“testbox”: “^5.4.0”
},
“devDependencies”: {
“commandbox-dotenv”: “^3.0.0”
}

Step 4: Define scripts for common tasks

  • test: Run your TestBox specs.
  • build: Produce an artifact or run linting/prep steps.
  • release: Automate version bumping and tagging.

Example:
“scripts”: {
“test”: “testbox run”,
“build”: “echo Building…”,
“release”: “package version –bump patch && git push –follow-tags”
}

Run scripts with:
box run-script test

Step 5: Validate and publish (if public)

  • Validate box.json:
    • Use your editor’s JSON schema validation or linting
  • Test locally:
    • box install
  • Publish to ForgeBox (public):
    • box publish
  • Keep an eye on the slug and version; both must remain consistent and valid.

Best practices

Versioning and release hygiene

  • Adopt semantic versioning strictly: MAJOR.MINOR.PATCH
  • Automate tagging in CI so the box.json version matches your Git tags
  • Avoid accidental breaking changes in minor/patch releases

Dependency management

  • Prefer version ranges that reflect your compatibility guarantees
  • Lock critical dependencies when stability is essential
  • Periodically review transitive dependencies to prevent drift

Discoverability and documentation

  • Maintain clear descriptions, keywords, and homepage links
  • Include README.md, CHANGELOG.md, and CONTRIBUTING.md in your repo
  • Add examples that demonstrate quick wins for users

Publishing and private packages

  • If internal, mark it clearly in your docs and keep the package private in your registry
  • Consider separate templates for internal and external distribution to avoid leaks
  • Store environment-specific secrets outside of box.json; use environment variables or secure config

CI/CD Integration

  • Run box install and your test script on every PR
  • Validate JSON schema in CI to catch errors early
  • Automate releases from main/master with controlled version bumps

H5: Advanced fields and patterns (when applicable)

  • installPaths: Control where dependencies get installed in your project
  • excludes: Exclude files or directories from package distributions
  • engines or compatibility notes in docs: Clarify supported Lucee/ACF versions
  • hooks and lifecycle: Use scripts to generate docs or run preflight checks before publishing
See also  Download ColdFusion CORS Policy Examples

Benefits and Use Cases

  • Teams adopting ColdBox or CommandBox at scale: Shared templates reduce Onboarding time and avoid inconsistent metadata.
  • Library authors: Ship predictable packages with clean manifests, reliable dependencies, and documented scripts.
  • Private enterprise distributions: Keep internal modules standardized and safe to consume across multiple apps.
  • CI/CD pipelines: Faster, repeatable builds thanks to consistent scripts and versioning rules.
  • Education and Onboarding: New CFML developers learn ForgeBox/CommandBox conventions by example.

How this saves time and improves quality:

  • Eliminates guesswork around required fields and valid structures.
  • Minimizes “works on my machine” issues by codifying dependency and script patterns.
  • Encourages better release discipline and reproducible builds through tested templates.

Key Takeaways

  • The library supplies ready-made, field-annotated box.json templates for ColdBox apps, modules, libraries, CLI commands, and private packages.
  • You’ll accelerate setup, improve consistency, and reduce publish/install errors.
  • Scripts, dependency ranges, and metadata are modeled after current CommandBox and ForgeBox Best practices.
  • Use editor validation and CI checks to ensure the manifest remains valid as your project evolves.
  • Choose the template that matches your distribution strategy (public vs. private) and target environment (Lucee/ACF).

FAQ

How do I run scripts defined in box.json?

Use the CommandBox script runner. For example: box run-script test. Define your scripts under the “scripts” key in box.json and reference CLI commands available in your environment.

Can I keep a package private and still use these templates?

Yes. The library includes a private-package template and guidance to avoid public publication. You can manage internal modules via private registries or local installs.

What version of CommandBox is required?

The templates are designed to work best on CommandBox 5.x and 6.x. If you’re on an older version, validate fields in your editor or CI and adjust scripts to match supported Features.

Do the templates enforce a specific CFML engine?

No. They’re engine-agnostic. You can target Lucee or Adobe ColdFusion; note compatibility in your README and tests. Use CI to test across engines as needed.

How should I choose dependency version ranges?

Use caret ranges (^) when you trust semver adherence and want non-breaking updates, tilde (~) for patch-level updates only, or exact pins for maximum reproducibility. Match this choice to your stability needs and support policy.

About the author

Aaron Longnion

Aaron Longnion

Hey there! I'm Aaron Longnion — an Internet technologist, web software engineer, and ColdFusion expert with more than 24 years of experience. Over the years, I've had the privilege of working with some of the most exciting and fast-growing companies out there, including lynda.com, HomeAway, landsofamerica.com (CoStar Group), and Adobe.com.

I'm a full-stack developer at heart, but what really drives me is designing and building internet architectures that are highly scalable, cost-effective, and fault-tolerant — solutions built to handle rapid growth and stay ahead of the curve.

View all posts

You may also like