'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:
- A folder
- With some code (cfm or cfc files)
- 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
> 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:
- Everything a package is
- 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:
- A web UI located at https://www.forgebox.io/
- A REST API located at https://www.forgebox.io/api/v1/
- A set of CLI commands in CommandBox (that use the REST API)
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.
> 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
> mkdir mypackage --cd
> !git init
> package init slug=my-package type=modules location=gitUser/my-package
> bump --minor message="Initial Commit"
# Publish it
> !git remote add origin <git url>
> !git push
> 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!
> forgebox show my-package
> install my-package
Read more at our docs here: