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

Thanksgiving Day deals: Access Exclusive Discounts Until November 30th!

Thanksgiving Day deals: Access Exclusive Discounts Until November 30th!

Prepare for the Ortus Thanksgiving Day Deals! This is your chance to enhance your development journey with amazing deals catered to everyone—from experienced developers to tech aficionados. Our unique offers are crafted to assist you in reaching your objectives while conserving your budget!

Don't Let These Incredible Offers Slip Away!

Utilize the code THKSGIVING24 at checkout to take advantage of these fantastic discounts before they end...

Cristobal Escobar
Cristobal Escobar
November 04, 2024
BoxLang Newsletter: October 2024

BoxLang Newsletter: October 2024

Welcome to the October edition of the BoxLang Newsletter! **This month has been packed with exciting updates, new features, and enhancements that continue to shape BoxLang into a robust and versatile programming language. In this edition, we highlight the latest beta releases, new integrations, and key features that have been introduced.

Maria Jose Herrera
Maria Jose Herrera
November 04, 2024
BoxLang 1.0.0 Beta 21 Launched

BoxLang 1.0.0 Beta 21 Launched

This release brings another round of powerful tools and refinements to the BoxLang community, making development more dynamic and robust than ever. We’ve added new capabilities for debugging and tracing, expanded context-sensitive controls for thread management, and introduced new methods for fluent attachment handling.

For deeper flexibility, our improvements enhance configurability, streamline session control, and add deeper levels of JSON serialization management. Plus, we’ve squashed a wide range of bugs, enhancing stability across database connections, date handling, and runtime compatibility with CFML.

In addition, CSRF Token functionality is now provided via the bx-csrf module.

Luis Majano
Luis Majano
November 01, 2024