Blog

Brad Wood

December 16, 2017

Spread the word


Share your thoughts

'Tis the season to share with others.  And what a perfect time to talk about sharing your CFML libraries!  How many times do you think CF devs have written the same libraries and integrations over and over, just to keep their work to themselves.  Giving your work back to the community is what makes the world go 'round and also makes the CF space more attractive to outside developers looking in.

What is a package?

A package is the most generic form of reusable code.  It is simply:

  1. A folder
  2. With some code (cfm or cfc files)
  3. A box.json

That last item (sometimes called the package descriptor) is the magic that allows package management to happen. It describes the metadata of your package.  What it's called, what version it's at, who wrote it, and what other packages it depends on to run.  

A package can be a complicated API integration or as simple as a single CFC with a handy method in it.  To create a new box.json file, run the init command.  Or if you'd like some hand-holding, start with the init --wizard to walk you through it

CommandBox> init

That's it!  Sure there's more to it, but that is the bare minimum you need to create a shareable package of code.

Packages/Modules

You may be wondering what the difference is between a package and a module if you've heard both terms thrown around.  Well, modules are packages, but not all packages are modules.  A module is specific to a *Box product like ColdBox, ContentBox, or CommandBox.  A module is defined as:

  1. Everything a package is
  2. With a ModuleConfig.cfc

Modules also have additional convention folders they might use, but that's all optional so we'll ignore it for now.  CommandBox can be used to wrap up any folder of code into a shareble package, however if you're on one of the Boxen, modules give you another level of metadata, conventions, and power to your code sharing.  

Where do packages/modules live?

Well technically, they can live anywhere.  For the sake of this discussion, you want your packages to be registered on forgebox.io.  ForgeBox is the online code repository for modern CFML and it is open to any and all CFML packages, regardless of whether or not they are Box modules.  Heck, ForgeBox is even home to FW/1, Taffy, Mura, etc.  ForgeBox comes in three parts:

Anyone can anonymously browse the install the projects on ForgeBox, but if you want to publish your own packages, you'll want to register for your own free account.  You can create a ForgeBox account quickly and easily from the CLI.

CommandBox> forgebox register

Once you finish, click the link in your E-mail to activate your account and you'll be "logged in" from the CLI so any forgebox commands you run are performed as your user.

How do I get started?

Ok, you probably already have a little library in mind that you've written and always wanted to get out there but wasn't sure how.  The best way to get started by publishing your first package is simply to dive in and give it a try.  Once you've done it a couple of times you'll get the hang of it.  And don't worry, there's an unpublish command in case you want to start over!  Here's what you'll need:

  • Your forgebox account created and logged in.  Test this by running forgebox whoami
  • Your package created in a local folder with the box.json present
  • in you box.json you'll minimally need these properties defined
    • name (human readable)
    • slug (must be unique)
    • version (follow the 1.2.3 semantic versioning)
    • location (points to where the code lives)

The easiest way to point to your code is to push your changes to a GitHub repo and point your location at that repo.  CommandBox has some helpers for this.  If you use the bump to increase your version numbers, it will automatically tag your Git repo for you.  

Here's all the commands you need to start from an empty folder and have a package published for the world to see.

# Create package/git repo
CommandBox> mkdir mypackage --cd
CommandBox> !git init
CommandBox> package init slug=my-package type=modules location=gitUser/my-package
CommandBox> bump --minor message="Initial Commit"

# Publish it
CommandBox> !git remote add origin <git url>
CommandBox> !git push
CommandBox> publish

 Once you've done that, you can test your new package with these commands in a new folder:

# Viewable and installable by the world!
CommandBox> forgebox show my-package
CommandBox> install my-package

Read more at our docs here:

https://ortus.gitbooks.io/commandbox-documentation/content/packages/creating_packages/creating_packages.html

 

Add Your Comment

Recent Entries

Must-See ITB 2025 Sessions for TestBox Users!

Must-See ITB 2025 Sessions for TestBox Users!

Are you a fan of TestBox or looking to level up your testing game in 2025? Whether you're just getting started with unit testing or you're already building advanced specs for ColdBox and BoxLang apps, Into the Box 2025 has an exciting lineup tailored just for you. Into the Box 2025 has an exciting lineup tailored just for you. With the recent launch of TestBox 6.3.0 we have amazing new tools, features and tips and tricks to get your testing experience to the next level, review our sessions and test like a pro efficiently and easy!

From hands-on testing strategies to BoxLang innovations, here are the sessions you won’t want to miss this May — and why they matter to you as a TestBox user.

Maria Jose Herrera
Maria Jose Herrera
April 17, 2025
The Into the Box 2025 Agenda is LIVE and Done!

The Into the Box 2025 Agenda is LIVE and Done!

The wait is over! The official Into the Box 2025 agenda is now live — and it's packed with high-impact sessions designed for modern CFML and BoxLang developers. Whether you’re building APIs, modernizing legacy apps, diving into serverless, or exploring AI integrations, this is the conference you’ve been waiting for.

Here’s a look at what you can expect — categorized by key topics to help you plan your learning journey, there’s something for everyone covering modern CFML tools and BoxLang:

Maria Jose Herrera
Maria Jose Herrera
April 15, 2025
Only 2 Days Left to Lock In Early Bird Pricing for Into the Box 2025!

Only 2 Days Left to Lock In Early Bird Pricing for Into the Box 2025!

The countdown is on. You have just two days left to secure your Early Bird ticket  for just $199 to Into the Box 2025 before prices increase on April 16.

We are proud to offer an engaging and high-value online experience for developers around the world. With a virtual ticket, you get more than just access — you get ongoing value that supports your growth long after the conference ends.

Maria Jose Herrera
Maria Jose Herrera
April 14, 2025