Building and Publishing a Cosmic JS Extension Using Bitbucket Pipelines

Cosmic JS just released their new Extension functionally, which enables anyone to embed their own custom app inside the Cosmic CMS! In this tutorial we’ll be going through some of the steps required to make our Amazon Product Search Extension. TL;DR View the full codebase on GitHub Install the Extension in your Bucket in Your Bucket > Extensions > Browse Extensions for more information on building an Extension View the Extension documentation The extension we’re building We’re building a simple Extension that allows you to search the Amazon Product Catalogue and add Objects to your bucket with products’ name, description, image, and an affiliate link. This is quite a simple app, built using react, and we won’t be going into too many details on the parts that don’t directly relate to the new Cosmic JS Extensions API. Getting access to the Cosmic API in your Extension Cosmic JS embeds extensions as an inside its CMS interface, the extension is given a url with a querystring providing all the information needed for your app to access the relevant bucket like so: https://43d32000-5ce7-11e7-8fc4-c1f6eec4f920.cosmicext.com/?bucket_slug=my-bucket-slug&read_key=foo&write_key=bar Extracting these variables, is very easy, and even easier using a library like qs: qs ; { bucket_slug, read_key, write_key, } = qs.parse( .location.search.slice( , )); .log({ bucket_slug, read_key, write_key, }); import from "qs" const window 1 Infinity console These keys can then be used to make API calls on the bucket your currently using the extension in: fetch( , opts, ); `https://api.cosmicjs.com/v1/ /object/amazon-credentials ` ${bucket_slug} ${ read_key ? + read_key : } "?read_key=" "" In our app we use these keys to add new object for Amazon Products that we find. extension.json One file that must be included in your extension is the file. This tells Cosmic important metadata about your app, like it's name, icon, display image, and the default Objects and Object Types that should be created when the Extension is first installed. The for our app is as follows: extension.json extension.json { : , : , : , : [ { : , : , : , : [ { : , : , : , : }, { : , : , : , : }, { : , : , : , : } ] } ], : [ { : , : , : , :[ { : , : , : , : , : , : }, { : , : , : , : , : , : } ] } ] } "title" "Amazon Product Search" "font_awesome_class" "fa-shopping-basket" "image_url" "http://fla.fg-a.com/shopping-cart/shopping-cart-black-3.png" "objects" "title" "Amazon Credentials" "slug" "amazon-credentials" "type" "amazon-credentials" "metafields" "key" "amz-key" "title" "Key" "type" "text" "value" "" "key" "amz-secret" "title" "Secret" "type" "text" "value" "" "key" "amz-tag" "title" "Tag" "type" "text" "value" "" "object_types" "title" "Amazon Products" "slug" "amazon-items" "singular" "Amazon Product" "metafields" "key" "image_url" "type" "text" "value" "" "title" "image_url" "parent" false "children" null "key" "affiliate_link" "type" "text" "value" "" "title" "affiliate_link" "parent" false "children" null The field is the name that your extension will display inside Cosmic The field must be a valid icon name the field is a display image that will show with your extension. title font_awesome_class Font Awesome image_url You also have space to specify a list of objects that will be created when your extension is installed, here we’ve detailed an object that will store our Amazon Product Search credentials. This means that Cosmic will handle saving this information for us! Deployment and Continuous Integration Uploading your extension to Cosmic is very easy, you just need to take a folder that contains you file, and an file (and any other assets you need), zip it up, and upload it. extension.json index.html Our build folder looks like this: build ├── extension ├── index └── static └── js └── main .json .html .a651cd8a .js You can either upload your zip file through the Cosmic JS CMS, or by using the rest API. We use Bitbucket to host our code, which has a built in CI service called Pipelines. You can configure pipelines to run on every commit to the branch of your git repo, and to upload the newest version of your app to Cosmic's servers. master We’ll configure our Bitbucket Pipeline like so: image: codogo/pipelines-universal:latest pipelines: branches: master: - step: script: - yarn install - yarn run lint - yarn run build - ./uploadNewExtension.sh Where contains: uploadNewExtension.sh EXTENSION_NAME= PREVIOUS_EXTENSION_ID= ) null There is no extension on cosmic to delete Found id : deleting old extension... https://api.cosmicjs.com/v1/ /extensions/ {\ -H > /dev/null curl --progress-bar --url --header --form --form > /dev/null #!/bin/bash # $BUCKET_SLUG, $READ_KEY, and $WRITE_KEY are environment variables " " ${EXTENSION_NAME:-Amazon Product Search} echo "geting previous version extension id..." " ) | .[0].id" $( curl --progress-bar "https://api.cosmicjs.com/v1/extensions-2?hide_metafields=true&read_key=foo" | jq -r ".bucket.extensions | map(select(.title == \"$EXTENSION_NAME\" ) " # jq is a neat little program for extracting data from json, it is available here: https://jqplay.org/ if [ " $PREVIOUS_EXTENSION_ID " == " " ] ; then echo " '$EXTENSION_NAME' " else echo " for '$EXTENSION_NAME' $PREVIOUS_EXTENSION_ID " echo " " curl --progress-bar -X DELETE " $BUCKET_SLUG $PREVIOUS_EXTENSION_ID " -d " "write_key\":\" \"}" $WRITE_KEY "Content-type: application/json" fi echo "upload new version of extension..." "https://api.cosmicjs.com/v1/ /extensions" $BUCKET_SLUG "content-type: multipart/form-data" "write_key= " $WRITE_KEY "zip=@./build.zip" This script will remove any previously uploaded versions of our extension, then take our zipped Extension and upload it to our bucket. Summary In this tutorial we’ve had an introduction to the way Cosmic JS hosts and integrates with your Extension, and an explanation of how to upload your Extension using Bitbucket’s Continuous integration. If you’ve learnt something, please ! share this article If you’re making an extension, or anything else, with Cosmic JS or , we’d love to see what you’re making. get in touch on our Slack Twitter This post was written by , an award-winning digital agency with a passion for creating amazing digital experiences. Codogo This article was originally published on . the Cosmic JS Blog