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

BoxLang 1.0.0 Beta 23 Launched

BoxLang 1.0.0 Beta 23 Launched

The latest release of BoxLang, Beta 23, marks a significant step forward in our journey to create the ultimate dynamic language for the JVM. Packed with powerful new features, important bug fixes, and thoughtful optimizations, this update is designed to make your development experience smoother, faster, and more reliable, especially after now starting to take 100s of comments and bug reports from our community.

Luis Majano
Luis Majano
November 23, 2024
TestBox Latest Updates and News!

TestBox Latest Updates and News!

We’re thrilled to have launched the new TestBox website and TestBox 6.0! If you haven’t had a chance to explore yet, visit TestBox to discover updated documentation, powerful resources, and features that make testing more efficient than ever.

Maria Jose Herrera
Maria Jose Herrera
November 21, 2024
Is Your ColdFusion Application Ready for the Future?

Is Your ColdFusion Application Ready for the Future?

In a rapidly evolving digital world, maintaining performance, security, and scalability for ColdFusion applications is more challenging than ever. Whether you're using Lucee or Adobe ColdFusion, legacy systems can become a bottleneck for growth, innovation, and user satisfaction. The need to future-proof your ColdFusion applications has never been more critical.

But where do you start?


The Hidden Costs of an Outdated ColdFusion Application

As you...

Cristobal Escobar
Cristobal Escobar
November 21, 2024