Are you a Trello enthusiast looking to start developing you own Power-Up? Trello Power-Ups are custom integrations add new functionality to your Trello boards, and creating one yourself is easier than you might think.
I created the following tutorial to walk you through the process of developing a Trello Power-Up in Visual Studio Code using npm (Node Package Manager). By the end, you’ll have a basic project that you can further enhance as needed. But this will take you some time. I took my time walking through this and it took me a good hour to get through all the steps below. The good news is once you have done this, you will have a quick, easy to use project that is totally reusable for multiple Power-Ups. With that said, let’s get started…
Prerequisites
Before we dive in, make sure you have the following prerequisites:
- Node.js and npm: If you don’t have Node.js and npm installed, download and install them from the official website here.
- Trello Account: You’ll need a Trello account to create and test your Power-Up.
- Visual Studio Code: If you don’t have VS Code, download and install it from https://code.visualstudio.com/.
- Once you have VS Code install, here are some suggested Extensions to make your life MUCH easier:
- ESLint
- Code Spell Checker
- Prettier – Code formatter
- Inline HTML
Something to read so you can get an idea of how powerful VS Code can be with extensions and other capabilities, here is more about JavaScript development in VS Code:
https://code.visualstudio.com/Docs/languages/javascript
Step 1: Create your Project Folder
In the least you ONLY need two files [index.js] and [index.html].
But it helps to build out your project with the proper folder structure right off the bat. So here are the folders I create:
- [certs] – required for local development and covered later
- [js] – for all your code files
- +– [common] – where you will keep common files (usually static defined stuff)
- +– [pages] – for all your js page files (more below)
- +– [components] – we will not get to this here, but might cover it in a future post.
- [types] – Go get this file: https://github.com/davecra/Trello-Power-Up-TypeDefs/blob/main/trello.d.ts, never Power-Up develop without it (*).
When I decided to make the Type Definitions file for Trello Power-Ups it CHANGED MY LIFE. Now, it is not perfect and I am still working on adding things to it, and find errors every now and then, but please notify me if you find anything wrong. But when I added this to my project it took the guesswork out of creating a Power-Up, in that “what does this return”, or “what are the properties of this or that.” And I did not have to have the Trello API reference page open in the browser all the time. My code got cleaner, more concise, and I was able to more quickly develop Power-Ups.
Step 2: Add files and Code
So, now we add the files.
If you do things “creatively” – correctly in my opinion – you really only need one HTML file for your WHOLE project even if you open multiple forms.
In the [views] folder, create the [index.html] file:
Now in the root of the [js/common] folder you will create a file [common.js]:
Now in the root of the [js] folder create the [client.js] file:
So, what this is doing is:
- Initializing the Trello Power-Up
- Hooking to the board buttons callback from Trello and adding a custom board button
- The button calls the Trello List Popup (essentially menu), when clicked.
- In that menu, I added ONE item, to show the settings in a pop-up iframe. Now, this is where things get interesting…
You might see how I might be doing something different from what Trello tutorials might have you doing. But if you look at the iframe reference, to Common.detailsPage, you will see that we added that as “details.html.” But WAIT, you did not ask me to create that page, so how is it going to work? Trust me, it will and in a moment, I will show you how it all works out. First clue is something called Web Pack. The second is pay close attention to the ARGS we are sending.
Next, create a new file called [details.js] and place it in the [js] folder with [details.js]. Here is the code for that page:
What we are doing here is setting this up for “reuse.” Gosh, I love that word. “Reuse,” said it again. REUSE. Ok…
So, we read the PAGE args (remember how I told you to pay close attention). I ask Trello for the arg passed call “page” and from that get which page to load. I then create an instance of a page object.
Now this is where I love, love, love ES6 and classes. I created an instance of the SettingsPage class and called render on it, passing the ever-important reference to the Trello context object (t). But what the heck, there still is not a Settings Page and details.html still does not exist??? Wait for it…
Now, in the [pages] folder, you will create the [settingsPage.js] file, and you will add this code:
What we are doing here is PURE ES6 GLORIOUS MAGIC. I generate a string using inline HTML (via the beautiful backtick), and you will see some VS Code fun stuff (/*html*/), this makes your code look like React inline HTML via the Inline HTML extension. OMG, it is awesome. Ok, then remember in the [index.html] file the div with the “id” of “content.” Well, I then assign the HTML string to the content div and viola, the settings page comes alive in the iframe of the Trello Popup window – just like that. And then because it is dynamic, I hook to the controls I created, add event hooks and such. I then call t.sizeTo() to tell Trello to fit the contents of the iframe neatly into the Popup window.
Hey, but there still is not a [details.html] page… should I not go and create that? NO!!! It’s coming, I promise.
Now, that is it for the code that makes your Power-Up tick. The rest is getting the development environment configured for runtime testing and building your code via Web Pack.
Step 3: Set Up Node and Web Pack
So, writing the code is half the battle. You could just make a copy if index.html and called it details.html place all the above code on a web server and call it a day. And everything will run.
But building a Power-Up and being able to update and test your code live is crucial to being able to make a compelling Power-Up in short order. You could just make changes, publish to the web, test, rinse – repeat. But it will take you a long time, frustration and for just a little more work, you will get SO MUCH MORE. And finally, your code will not be optimized (minified) for better browser runtime compile. So, here is how you round out your development environment for a Trello Power-Up.
Next thing you do is create a [package.json] at the root of the project folder. This file will tell NODE which packages to go pull of the Internet so that you can do the paragraph above. Here is the code:
The next thing you need is the Web Pack file. Ok, remember how I kept putting off the creating the [details.html] file. Wait for it…
The following file is going to look rather complex if you have not used Web PAck before. What this does it tells NODE how to “compile” your code and setup the development environment for local development testing.
So, let’s get started by adding the following file to the root of you project folder [webpack.config.js]:
I am not going into huge depth explaining this file as that is a whole post on its own. Bottom line what this is doing is configuring web pack. I will explain it like this:
- defines the core entry points as chunks [detial.js] and [client.js].
- in the plugins section, you will see the “reuse” coolness I was referring to above. On the fly we use the same file [index.html] for creating TWO files: index and details. And there you have it.
- the devServer is the last bit that makes this whole journey worthwhile. This creates a NODE server on your box, running on port 12345.
Your own Dev Server running locally on your box is the key but it will not work without this next bit. Trello REQUIRES all connections to be protected by HTTPS, so you MUST have SSL certificates.
Generating certs is a mild amount of pain, but with a LONG-TERM gain. So, you WILL need to do this part. And it is not hard. Here is how you generate a cert (and key) for yourself:
- Go here: https://slproweb.com/products/Win32OpenSSL.html
- Download the light version that is for your OS (for me it was Windows x64 – Light)
- Install it.
- Once installed you can run this command in VS Code (in Windows):
& "C:\Program Files\OpenSSL-Win64\bin\openssl" req -newkey rsa:2048 -x509 -nodes -keyout server.key -new -out server.crt -sha256 -days 3650- It will ask you for a passphrase (something like “test” is ok), and to confirm the passphrase, then country, state, city, company, unit, and such. Nothing is critical here, put what you want for these fields.
- It will create two files in the root of your project [server.crt] and [server.key].
- Move these files to the [certs] folder.
And this cert is good for 10 years, so you can add it to all your future projects.
You are now ready to start development. Open a terminal (press CTRL+`) and in the root directory of your project, run the following command to enable/init/update the project:
npm updateThis pulls in all the bits to make your development environment come alive.
Step 4: Setup Trello Admin Panel
To test your Power-Up, you can use the Trello development sandbox. Ensure you’ve created a Trello board and head to https://trello.com/power-ups/admin to enable the developer mode (see Trello documentation on this part).
Then, add your Power-Up to start testing. Here are the steps for our demo:
- Click New
- In the first field type “Hello World”
- Next, select your workspace.
- In the iframe URL, you type in your (soon to be launched local sandbox web server): https://localhost:12345/index.html
- Fill in the emails and your name fields, then click Create.
- You go to Capabilities and tick on “Board Buttons”
You are ready for the next step.
Step 5: Start your local web server and Test
In the terminal window, type this command:
npm startYou will see the web server start and now it is time to approve the certificate:
- Open your browser and go to: https://localhost:12345/index.html
- You will see a REJECTION, something like: Your connection isn’t private!
- You must click Advanced, then click [Continue to localhost (unsafe)]
You can get around this by adding the certificate to the Trusted Root Certificate Authorities on your computer. But that is different for Mac and Windows users, so I will let you look that one up on your own.
By the way, I never do that. I just ALWAYS run this step before I run locally. Just remember if you go into Trello and it appears to hang and your Power-Up is not loaded… did you forget this step?
Now we go to Trello to add your Power-Up. Go to Trello, and go to your board:
- Click Power-Ups, Add Power-Up.
- Go to the Custom option.
- Select Hello World, then click Add.
You will now see the [Hello World] board button appears. You are now running a local developer environment from VS Code with a live running debug in Trello. Go make a code change, refresh the browser and viola – your updated code changes are there and ready to test.
Now a word about “DEBUG.” I have not found a way to really hook up VS Code to Edge/Chrome yet and live debug. I am sure there is a way and if someone knows, please add a comment — I will give it a whirl and add a future post. What I do instead is open F12. When I get an error, it usually tells me the exact line it failed on, and I can go there in VS Code. I also use a lot of console.log() statements to follow code flow and get results. And when I feel particularly stuck, I though in a good debugger; line or two in the code so the F12 tools stop, and I can review things there. In the end this has worked rather well, but I really would like to be able to set a breakpoint in VS Code too… for now, I am happy enough.
Conclusion
Creating a Trello Power-Up in Visual Studio Code using npm is the only way to go as far as I am concerned.
Happy coding, and remember, the possibilities are endless when it comes to creating Trello Power-Ups to match your specific workflow. And over time, I will probably extend on this Power-Up tutorial as I find new things to write about.