DEV Community: Jacob Knaack

Creating a Bash Command

Jacob Knaack — Tue, 10 Sep 2019 20:01:39 +0000

Let's walk through the process of adding a fresh baby bash script as a command that you can run in your terminal.

Say you have a super rad script that does mega cool things somewhere on your computer:

hello-world

#!/bin/bash


echo Hello world

Allowing your bash terminal to run this script file as a command just takes a few simple steps.

1. Place your script somewhere that scripts go.

I recommend creating a directory at ~/ called bin or .bin. The bin folder is typically where commands go, so I'm going to replicate this:

$ cd ~/

$ mkdir .bin/

$ mv path/to/script ~/.bin/YOUR-SCRIPT-NAME

2. Add this Directory to your PATH.

Add a line to your .bash_profile that will make sure your bash terminal has a path to this file when running your command.

If you don't have one create one with

$ touch ~/.bash_profile

.bash_profile

#Here's the line you should add:
export PATH=$PATH:/Users/YOUR-USERNAME/.bin

Now you can either restart your terminal at this point or source this file:

source ~/.bash_profile

3. Add Permissions for Users to run this command.

We'll use the illusive chmod command to let users run this newly created command:

$ chmod u+x ~/.bin/YOUR-SCRIPT-NAME

And that's it! You should now be able to run your script from anywhere in your terminal.

Making A Bunch of Requests from a Node Server? Try Promise.all!

Jacob Knaack — Tue, 30 Jul 2019 22:14:36 +0000

Sometimes you find yourself needing to make a ton of http requests. For the most part this a bad idea, and you should really be abstracting your requests and not hammering a REST API since that's how you break things on the internet.

Buuuuuut for testing purposes or just trying to get something to friggin' work, we might be feeling a lil' hacky. We are developers ya know, and girls just want to have fun!

Disclaimer:

Please don't use this on any existing REST service that you don't control. This will possibly break any rate restrictions that service has put in place, and worse case could overload their servers.

I found myself in one of these scenarios while testing a bunch of mock spreadsheet data, where I wanted to make hundreds of requests to some server routes our team was building. Thus, the advent of this Node code you see below you.

Before continuing, this hack expects some knowledge around JS Promises, ES6 Syntax, and Node Modules. With that out of the way let's look at this solution and break it down:

Our Solution

This module doesn't do anything super fancy. But it does utilize some super fancy built in javascript Objects.

It formats an array of promises that we can feed into Promise.all.
When those asynchronously resolve we get a big happy bundle (an array for those strictly typed folks) of response objects :).

How do we Achieve this?

We leverage a handy Array prototype .map method to turn our array of request options, into new array containing promises:

const promiseArray = reqArray.map(req => new Promise(
  // things our Promise should do
));

Each Promise will resolve result of the request or reject the error if the request fails, asynchronously of course:

async (resolve, reject) => {
  try {
    resolve(await httpPromise(req));
  } catch (err) {
    reject(err);
  }
}

finally we just return the result of Promise.all which we pass our newly created array of Promises, or console an error if we get errors in those requests.

return Promise.all(promiseArray)
  .then((responses) => responses)
  .catch(err => {
    return { "message": "bulk request failed", "error": err }
  });

Hope this helps with whatever crazy asynchronous actions you're trying to accomplish. This can easily be refactored for use in other environments besides Node and can be used with other events (Database queries, Cloud Resource Interactions) that you want Javascript to handle only upon completion.

Happy Hacking :)

Building a Full Stack SMS-enabled Chat Application using Twilio, Node.js, GraphQL and Cosmic JS

Jacob Knaack — Fri, 21 Jun 2019 19:55:35 +0000

What a day to build! Today we are exploring how far chat has come, and how easy it is build a fully functional chat application complete with the ability to send SMS messages with just a few (super-rad) developer tools that are available to anyone with fingertips. There's quite a lot to cover so let's dive in!

TLDR:

Node.js Chat App Demo

Node.js Chat App Source Code

Introduction

Let's talk about goals, what we want to accomplish in the next hour or so.

Our application is at it's core a chat system. We're going to keep things very simple here. Our system will be able to register new users with minimal user information, create and emit messages to users in the chat room, and finally log users out of the chat room when they want to leave.

For bonus points we are also going to configure our system with an SMS notification system, that will send a Text notification to an admin account whenever a message is sent across our system. Pretty cool right?

Before We Start

This system is going to utilize a number of technologies to function. Most importantly Cosmic JS for managing all of our data: our Users, and our Messages. In order to follow along with this tutorial you should a free bucket on their platform and create a User and a Message Object.

in order to send SMS messages we are leveraging Twilio. A communications platform that allows developers to make phone calls and send text messages through a web API. To implement our notifications you'll have to register for a free Twilio number and start a trial account.

Software Requirements?

We are using Node JS as our runtime environment so please be sure you have a recent(ish) version of node installed. With that business out of the way we can start building.

High Level Overview

This is a full stack application, which means we are building a web-server to handle our requests and serve our client side application. We are going to create an Express application that will run on our Node JS server to handle routing to a small API and serve HTML, and Webpack to bundle our client interface built with React and Graphql. This way we can utilize a central server to make requests to the different parts of our application: our Interface, our Controllers, and our Web Services.

There are quite a few moving parts here so let's jump in!

Building Our Web Server

This is backbone our our app which will allow us to control the various pieces of our core application. We are going to start by creating and initializing a project directory where all of our dependencies will be installed. Let's open up our terminal and create some files:

$ mkdir chat 
$ cd chat

This creates a directory called chat and changes our current directory into that chat directory. Now we can initialize this directory as a Node project:

$ npm init

Your terminal will present you with a couple of prompts to create our package.json file that will contain most of the metadata about our project. I recommend hitting the enter key through these steps unless you know some specific information you'd like to give your application. You can always change these values later.

Now let's install some Node Modules we need to run our project and save them to package.json dependency list. We are going to install our bundler webpack along with the necessary loaders we need to bundle our JS, HTML, and SASS /CSS files as well as our server framework express:

$ npm install --save webpack webpack-cli clean-webpack-plugin @babel/core @babel/preset-env @babel/preset-react babel-loader file-loader sass-loader css-loader node-sass url-loader style-loader express express-session cookie-parser body-parser socket.io socket.io-client cosmicjs dotenv

We are saving these all as project dependencies since any deployment container we use will need to use these to build and run our application.

Next we are also going to install the dependencies required for rendering our User Interface:

$ npm install --save react react-dom react-router-dom react-icons graphql react-apollo apollo-boost axios

Setting Up Our Entry File

Now that we have some dependencies installed, we need to create an entry file that will handle all of the requests to our application. When a user makes a request to the default route '/', we will serve an HTML file. When the client makes a request to our API, we use endpoints appended with '/api'. The first step is just creating the file:

$ touch index.js

Let's open this file in our text editor and set up Express so that we serve some HTML when a browser navigates to our localhost server:

We are looking for an index.html file that is kept in a directory located at ./public so let's go ahead and create this file at ./public/index.html and insert some boilerplate to make sure our HTML is being served by our express server.

We should be able to start our server using node:

$ node index.js

When this command runs we should see a simple console message:

Cosmic Messenger listening on port : 3000

Now pointing our browser to http://localhost:3000 will show us a mostly blank screen but now we see a little "Hello World" at top of our page. Now our server is set up to serve content from our html file.

Configuring Webpack

We want to build our interface with React, but we need to serve this interface from a directory that our node server can access. We also need to compile our javascript from the fancy syntax that we use to build our components to something that all browsers can process. To do this we are going to use Webpack to bundle all of our files into a specific location, and Babel to compile all of our code.

Let's create a file called webpack.config.js and add some configuration for bundling our client interface:

This is going to allow us to create source code and organize it in a meaningful way using whatever directory structure we like for structuring logic, then bundle it all into one file that our index.html can reference while it's served from our webServer.

Initializing Our React App

We have our config file created, but now we need to create some source code and make sure webpack bundles everything properly. Let's go ahead and create a folder called src and touch a file called app.js within. From there we can create a simple React component that will render the same thing as before, but now we are serving javascript bundled together and injected into our index.html served from our web server. Server side rendering baby!

Here's what our app.js file will look like initially:

Before we run webpack and serve our interface we need to install some developer dependencies and add some simple configuration values to our package.json. Specifically we need to tell our server that we are using babel to compile our interface code and some npm scripts so that we can run our Web Server and bundle our React code.

Let's install some dependencies that we only need to use for local development purposes:

$ npm install --save-dev morgan nodemon webpack-dev-server

With those installed, let's open package.json and add a prestart, start, and dev properties to our scripts object as well as a babel config object. Here's how things should look:

Now we can run webpack and node simultaneously by simply running:

$ npm run dev

In a second you'll see some output text from webpack:

Heading back to http://localhost:3000 should produce the same result as before, but now we are serving a React application allowing us to create sensible component classes and render them within our index.html.

Creating our REST API

We are going to interface with our Cosmic JS resources by making requests to our server code via express routes which we'll configure right now.

We will need three POST routes that will handle requests to our server. One for registering users that visit the app, one for messages that get sent through the messenger, and a logout route for users wanting to leave the chat.

We also want to configure middleware for handling the request bodies sent through our api, body-parser, a module for creating session cookies to weakly authenticate requests to our messaging service, express-session. Finally we need to configure web sockets so that we can emit events to all the clients connected to our server via socket.io.

Socket.io will emit 3 separate events for the time being: One when a user registers so that other clients can track who is logged in to the app in real time. Inversely, we are tracking a logout event that will let user know when users have left the chat. And one for when a *message is sent.

If you didn't install them at the beginning of our server setup, you can install them with a quick npm command:

$ npm install --save socket.io socket.io-client express-session body-parser

Now let's open up our entry file: index.js, and add our routes and middleware configuration:

You'll notice several new libraries we are importing. Most notably we are using a middleware called twilioNotifications and cosmicjs which need to be configured before our server will function properly. For twilio notifications to work, we need to create some middleware that will control when an SMS message is sent. We also need to configure this middleware with authentication tokens and keys for the twilio web server. For cosmicjs we need to do the same, grab some Auth Tokens and save them in our environment variable config file.

Configure Our Environment Variables

Let's create a file called .env at the root of our project directory. In it we'll need to store some environment variables, but also some sensitive config variables for our web services. Here's what you need:

You'll need to grab two sets of authentication credentials for our environment variables. From twilio you'll need your ACCOUNT SID and AUTH TOKEN as well as the phone number associated with your account, which will be located at https://www.twilio.com/console. From cosmicjs we need to grab our read and write keys to authenticate our requests. These can be found at https://cosmicjs.com/cosmic-messenger/settings/main. You may have to generate these from the general settings panel.

Once these are here we must update our webpack.config.js so that we can reference these variables in our client side javascript. The updated file should look something like this:

You'll notice that we added some global app variables using the DefinePlugin method of webpack. Now these variables can be used globally throughout our application thanks to Webpack's bundling.

Our SMS Notification Middleware

Create a directory called middleware and place a couple files within:

$ mkdir middleware 
$ touch middleware/twilioNotifications.js middleware/twilioClient.js middleware/config.js

Our twilioClient file will handle making the request to the Twilio API:

Our twilioNotification file will handle the request object from express and make sure that any routes that use the module will trigger the Twilio client:

Finally we are going to create a config.js to configure our middleware with the necessary configuration variables required to make our app play nicely with Twilio's API::

Now our app is all set to function as a chat server. All thats left is to create our React components and make them talk to our server to function as a chat interface.

Building Our Interface Components

Our interface will be very straight forward. We'll start by building out our app.js file and set up two routes, one for our registration form, and another for our chat input, messages, and user list. We also want to configure our graphql client so that we can fetch data directly from Cosmic JS when we are render each page.

Let's create a folder called components under the src directory. In here we will put all of our React components that we want to import into app.js.

Now we need to create our two components rendered within our routing logic: Chat and loginForm. We'll start with our login form at src/components/loginForm.js:

Next we need to create the components for our chat form, for which we'll create a new directory called chat in the components directory. In here we'll create three files, one for the parent chat form component: src/components/chat/index.js:, one for the list of messages: src/components/chat/messageList.js and one for the list of users: src/components/chat/userList.js. Let's start with our chat form:

This component contains our message form that sends text data to our chat server. You'll notice it also emits an event using a module we need to build for handling web socket events. We'll get to that in a second, before that let's create our userList and messageList:

Our UserList simply displays our user's within our UI. It fetches those users from Cosmic JS's graphql servers and then subscribes to our socket module which refetches data every time our server emits those events.

Now let's create our MessageList:

Now Let's create our socket module that will let these components subscribe to our server events. Create a new folder called lib and create a file within called socket.js:

With that, we now have a complete full stack chat application, equipped with a client interface rendered server side. With a bonus of notifying an admin when messages are sent over the server.

Next Steps

Since this app is built and run completely from web server, we can easily deploy this using any hosting service that supports Node JS containers. I'd recommend Heroku or Cosmic JS since they both support project structures like this and can quickly create deployments.

That's all for me this week ya'll. Until the next time.

Building and Designing a Portfolio Site Using Gatsby JS and Cosmic JS

Jacob Knaack — Wed, 15 May 2019 16:35:09 +0000

Creating / updating our portfolios is a necessary evil these days. Places change, people change, and thus the cycle of content creation and management churns continuously. When you find yourself in need of a portfolio redesign, there are tons of tools and services to consider. One that should currently peak your interest is the Gatsby JS static site generator along with a headless CMS, like Cosmic JS. Today, with these two tools, we will create a working portfolio ready for continuous deployment, with the power to be rebuilt when content changes are made.

TLDR:
Gatsby Portfolio Site Demo

Download the Codebase

0.0 Before We Start

We are creating a portfolio site mostly with static data, but it would nice to be able to easily modify the content of our site without needing to modify a bunch of source code. So we are building a client that consumes content stored on a Content Management Service and programmatically displays it at whatever URL we choose.

0.1 Tools We Are Using

Gatsby JS - This is a static site generator that will automatically fetch new data and rebuild our site files when changes are made to our content. Comes bundled with data fetching wizardry GraphQL and the ever present React JS front end framework.
Cosmic JS - Our Content Management Service that will store all the information we need about our site. Cosmic JS offers very flexible data model definition that will allow us to store all types of information, from iterables to simple text fields and HTML content. NOTE! - In order to follow along with this tutorial you will need to create a bucket on Cosmic JS and fill it with the appropriate data objects.
RSuite - A library of pre-styled components that works with react to give us pre-styled components. This will allow us to use components that look great out of the box, while also giving us flexibility to make adjustments as needed.
Netlify (Optional) - A deployment service that will let us hook directly into a git repository. Using this we can configure webooks for rebuilding static files as well as make automatic deploys when source code changes occur.
Let's go ahead and begin configuring our setup.

1.0 Installation and Setup

We only have a few software requirements needed to start building. Mainly we need Node JS either npm or yarn, and we will be using git to do some deployment things on Netlify if you so choose.

1.1 Initializing our Project

Once you get those installed, we can begin setting up our development environment. Gatsby uses a very handy dandy CLI to allow us to bootstrap our project with a project directory ready to build and serve from a Node environment.

If you don't have the CLI you can install it with a simple npm terminal command:

$npm install -g gatsby-cli

This will take a moment to install but after a few seconds you will have access to gatsby terminal command which we can use to initialize our project:

$gatsby new gatsby-portfolio

Now we have a directory called gatsby-portfolio in the location you ran the gatsby command, change to that directory and list its contents:

$cd gatsby-portfolio/ && ls -la

You should see a list of folders and files similar to this:

.
├── node_modules
├── src
├── .gitignore
├── .prettierrc
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── gatsby-ssr.js
├── LICENSE
├── package-lock.json
├── package.json
└── README.md

open up package.json and we will see we have some terminal scripts that we can now use to build / serve our project. Try running the start script in your terminal:

$npm start

$yarn start

After a few seconds we should see a success message in our terminal and we should be able to view our initial project view on our localhost, you should see something like this:

Great, now press ctrl + C within your terminal to stop the development server and we are now ready install our node libraries.

1.2 Installing our Libraries

We require a few plugins from Gatsby to allow our Graphql queries to run, as well as a few extras for environment configuration and our component library RSuite. From within your project directory, we need to run some terminal commands to get our js libraries:

$yarn add rsuite dotenv gatsby-source-cosmicjs gatsby-plugin-sass gatsby-
plugin-less node-sass less

Let's go through these and talk about what we are adding to our project here:

rsuite - our component library that I mentioned above. Installing this let's us import js classes and insert pre-styled React components.
dotenv - Allows us to configure our source code with sensitive api keys, token, whatever that may change between developers but should be present when the source code is built.
gatsby-source-cosmicjs - a gatsby plugin that will let us easily make graphql requests to the Cosmic JS graphql API.
gatsby-plugin-sass / gatsby-plugin-less / node-sass / less - Gatsby plugins and styling libraries that will let us use .scss and .less files. These will allow us to import rsuite styling specs and bundle them properly on build.

1.3 Configuring Gatsby

In order for Gatsby to be able to build our html files, we need to fetch data from Cosmic JS and build each page using the data graphql retrieves. Let's go ahead and open gatsby-config.js and add our installed packages:

The first thing you you should notice is our requiring of dotenv. This will make our environment variables accessible in this config file at run time and allow Gatsby to configure our components with our credentials needed to make API requests.

We have added our plugins for sass and less, and also added our gatsby-source-cosmicjs plugin. You'll notice that we are using some environment variables to configure this plugin so we need to add a hidden file that will store these variables.

$touch .env

Now add your variables to this file and dotenv will take care of defining these using line 1 of our gatsby-config.js file. You can find the value to assign to these variables from within your Cosmic JS bucket: Bucket Name > Dashboard > Settings > Basic Settings:

Now we are ready to build!

2.0 Building Our Components

So what are we building exactly. Well, basically we will create one large Page component and create a series of display components to handle each section of our portfolio. Let's break this down:

src/pages/index.js

This is our home page and where all of our components will be loaded and used to display portfolio info.

src/components/projects.js

This will be our projects section that will take project data and display information about each project. This will take a prop composed of our portfolio projects and iterate over them to display data when appropriate.

src/components/work.js

This will a section highlighting our skills and the types of services / work we offer to people that might peruse our portfolios.

src/components/about.js

This will be a section that talks about us, displaying any personal data we want to share.

src/components/contact.js

Finally we have a component that we will use for displaying a contact form that will let users email us if they have any inquires.

2.1 The Home Page

This is our main component that act as our entry point for our portfolio. Its job is to make several Graphql API requests for our portfolio data from Cosmic JS and pass that data onto the different sections of our portfolio. Let's look at the component and talk about what's happening:

The only display element that really lives here is the splash screen which gives us a little bit copy that can be displayed about your company. But the meat of our content will be pushed into each section component.

Now let's update the header so that we can navigate around our home page.

2.2 Modify the Header Component

By default Gatsby gives us a Layout component that lets us wrap each page with a Header and Footer. We are going to add some navigation for our portfolio into the header so users can navigate to different sections of our Portfolio by clicking on a nav bar that we will import from rsuite:

These links will scroll the home page down to each section via the name properties placed on each section on our home page.

2.3 The Work Component

This component takes in our data about any services we provide, specifically a names, a short summary, and a more in depth description, and let's us display that to our users:

This iterates through our services objects. For every service that exists we add a new div to the work component section. Now we can modify and add data to our services on Cosmic JS and it will update accordingly.

2.4 The Projects and About Components

These sections will behave in essentially the same way, we display some information from our Home page object from Cosmic JS. Just a bit of text to give the user some context for each section, but after that we just iterating through our list objects we have saved to our Cosmic JS bucket.

Here’s our Projects component that will iterate through our projects and display images and text:

The about component will behave the same way. It will iterate through a list of people and display some images and information stored in the services objects on Cosmic JS:

2.5 The Contact Component

Lastly we have a component that will users to contact us at an email we specify. This will handle our contact form, and will be initialized with some state variables so we can control our user inputs, all the input and form components are handled by rsuite so we don't have to add too many styling properties to our form fields and feedback components:

Essentially we validate our form fields by checking if all the form field contain a value, then we use a the mailto url to open an email client and populate it with our message.

3.0 Deployment (optional)

Now we are ready to deploy our app. The most important part of this process is making sure that our app rebuilds itself when we change any data on Cosmic JS. If we integrate continuous deployment using git Netlify will allow us to activate a buildhook in order to generate new static files using updated data fetched from the Cosmic JS API.

3.1 Deploying from Git

Go to Netlify and create an account if you don't aready have one. From the apps dashboard click New Site from Git at the app dahsboard. From there you will be walked through the process of authorizing Netflify to access a repository from a git service (github, gitlab, bitbucket).

You will have to add you COSMIC_READ_KEY and your COSMIC_BUCKET_SLUG as environment variables. This can be found under the deploy settings once the app has been created on Netlify. In the same area you can create your buildhook to allow Cosmic JS to request a rebuild of your files once an update is made:

Once the buildhook is created go over to Cosmic JS and add it to the webhooks tab under the settings for your bucket:

Follow the instructions for adding a webhook that fires a post request to that url from Netlify every time an object is updated and you should have a continuously deployed, super fast portfolio site ready to be updated.

Thanks for following along with me and I'll see you next time I decide to build something cool :)

Building a Progressive Blog App with Apollo and Cosmic JS

Jacob Knaack — Mon, 22 Apr 2019 16:18:54 +0000

Hello stranger. Come with me on a short adventure as we build a fast, simple interface for publishing blog style articles. Something sensible. It should look clean and simple yet have the ability to perform powerful resource fetching with some query magic. I'm talking about Graphql, the query language built with web APIs in mind. And speaking of web APIs, we will also be using our handy Content Management Service: Cosmic JS, to Create and Store our Blog Data.

TLDR:

Progressive Apollo Blog
Progressive Apollo Blog Codebase

0.0 Before You Start

Before you go any further make sure you have the required developer tools installed on your machine. Mainly you will need Node JS, its accompanying package manager: npm, and git. Git is semi optional and will only be used to code storage and deployment if that is your goal.

Once you have those installed we can begin setting up our project and eventually start writing some Javascript.

0.1 Libraries and packages

Let's go over the main packages that we will use to create our blog platform.

Create React App - We will be leveraging the ever prevalent React library to build our UI components. To bootstrap our project we will also be using a handy command line tool create-reate-app so that we can spend as little time as possible on configuration and setup and just get to creating meaningful javascript.
Semantic UI - This is a UI framework that will allow us to import fully styled UI components. No fussing around with tedious CSS specs to get something that looks nice right out of the gate.
Apollo / Graphql - These two packages go hand in hand. Apollo will be used as the Graphql client to make requests to our Graphql server endpoints. It's easy to configure and very straight forward to use. Again, allowing us to focus on writing less javascript and instead focusing on the high level composition of our application. Graphql of course will allow us to make requests that return only data we care about, letting us efficiently grab content from Cosmic JS.
I believe with all that boring business out of the way, we can start slapping our keyboards!

1.0 Setting Up Our Project

Let's fire up our terminal and start bootstrapping our project source files. For those that don't have Create React App installed, we can do that with a simple npm command:

$npm install -g create-react-app

Once this finishes (or you have this package already installed), we can summon our initial project files by running the cli:

$create-react-app apollo-blog

You will notice a fair amount of wizardry occurring in your terminal as our app is bootstrapped with all sorts of powerful libraries and source code. Taking a look at our file system will show a directory titled apollo-blog. Changing directories into this folder will show a structure similar to this:

apollo-blog/
    README.md 
    node_modules/
    package.json
    public/
        index.html
        favicon.ico
    src/
        App.css
        App.js
        App.test.js
        index.css
        index.js
        logo.svg

We should now be able to run:

$npm start

$yarn start

This will run the start script stored in our package.json file which is all bundled together with Webpack and build tools that will handle compiling all of our React source code and bundling that into files ready to be served to a browser.

After the script runs you should see a simple message in your terminal, and your default browser should open to a tab with project running. You should see something like this:

1.1 Installing Javascript Libraries

The next step is installing some npm libraries so that will help quickly create a good looking App Interface as well as easily fetch data from the Cosmic JS graphql servers.

In your terminal run the following command and let's talk about what each of these packages will be doing for us:

$npm install --save apollo-boost react-apollo graphql dotenv semantic-ui-css semantic-ui-react react-router-dom

apollo-boost / react-apollo / graphql - These guys are going to serve as the main solution for getting our data efficiently and scalably from Cosmic JS servers to our client side UI. They provide wrappers for our components to be able to configure queries and provide useful variables for data loading and error handling.

dotenv - this package will allow is to configure semi sensitive keys so we don't have to store anything publicly for accessing our Cosmic JS Bucket.

semantic-ui-css / semantic-ui-react - Our UI framework that will let us import pre-styled containers and components letting us focus on programming functionality, spending less time fidgeting with CSS and other styling considerations.

react-router-dom - A react library that will allow us to configure url routing logic to control linking within our app and accessing URL parameters.

with these installed we can begin writing some javascript!

1.2 Configuring Environment Variables

We are going to add a minimal security precaution so that we won't let just any request come through our bucket's API endpoint, feel free to skip this section but be warned that your components will behave a little differently and your bucket can be queried from anyone with the knowhow to make API Requests. So, you know... don't put any sensitive info in your buckets.

We are going to require a read_key to be attached to every API request to our bucket. You'll have to generate one by heading to the settings tab for your Cosmic JS bucket and clicking on Basic Settings. Cosmic JS > Your Bucket > settings > main.

At the top there should be as section titled API Access > API Read Access Key. Click on the button to Generate new key. Copy the key to your clipboard and let's configure our project directory with our config file:

$touch .env

this file is going to be used to configure our project with our API Read Access Key so we don't have to hard code it in with our source code and commit it for the world / other prying eyes to see.

simply add one line to your .env file:

Make sure you prefix your variable name with REACT_APP! The build scripts that bundle our source code will look for this to make variables available in our compiled javascript. With that done, we are now ready to use this key in our React project.

2.0 Creating our Routes and Components

Finally, we are ready to create our Components and set up our routes. In an effort to keep things as simple as possible we are just creating two routes and two main components:

Routes

{protocol}://{host}/

The home route that will list our articles.

{protocol}://{host}/article/:articleName

The route that will display an article.

Components

/views/home.js

This component will fetch all articles and display general article info.

/views/article.js

The component that will fetch a single article and display all article content.

2.1 Configuring App.js

Let's go ahead and open the App.js component in whatever text editor you prefer, and start to configure it with our routing logic and our Graphql client.

We are going to import one component wrapper from react-apollo and one constructor function that will let the components within our component wrapper make requests to a specified Graphql server ( for us this will be the Cosmic JS's Graphql server).

We also want to import our wrapping components for react-router-dom. This will allow us to us our browser url to systematically switch component views and access any url parameters.

Lastly we are going to import a CSS file from Semantic UI so that we can leverage it's class selectors and give imported components their base stylings.

Here's what our App.js should look like after everything is properly configured:

2.2 Creating The Home View

Let's create a new file in a new directory.

src/views/home.js

This folder will store all of our view layer React Components. Our Home View will just return some brief info about our site and a list of articles that have been published to our blog.

The main parts of this component are a heading that display a title and a site description, and a list that will display Semantic UI components.

We also will need to configure this view with some Graphql logic so that it can make requests to Cosmic JS.

Now we have ye old React Component, that will fetch articles from our content manager (Cosmic JS) before the component renders and pass those as an array on component props.

Apollo also gives us some handy properties attached to its data object, specifically an error object, and a loading boolean, which we use to conditionally render components, such as loading message when the request is fetching, and an error message when our error object returns a message.

2.3 Creating The Article View

With our list of articles displaying on our home page, we need to Create the view that will display the blog content contained in each article object.

Let's create another file in our views directory:

src/views/article.js

Creating this component is similar to the Home View, but our query is going to include an article identifier from our URL stored on a prop: match which react-router-dom creates for us when we render a component at a Route.

This component is much simpler than our Home component, mostly due to the fact that we are just using the Query component wrapper instead of the turning our component into a higher level component using the Graphql component. This gives us direct access to our Graphql directly in our component logic but does not make it available on component props! So take note.

For both components I have included some minimal styling objects in the source code, but feel free to use your creativity and change up the styling properties to create your own look and feel.

And that's it! We have built two relatively simple and scalable React components that are configured to two separate url routes. We can control our views easily with react-router-dom and fetch our data sensibly with the power of Apollo / Graphql and Cosmic JS.

3.0 Deployment

create-react-app comes bundled with some handy deployment scripts if you feel so inclined to make your application available to the world.

3.1 Running the Build Script

If you take a look at the package.json file that we have a script called build. Running this will compile all your project files and bundle them into a static build directory that is ready to deploy to any hosting service.

You'll also notice after the script finishes that you have an option to publish directly to github pages using the serve module. You just need to add a homepage value in package.json and make sure the serve package is installed with either npm or yarn.

Follow the link at the end of the build message to learn more about deployment using this method.

3.2 Deploying Using Netlify and Github

Netlify provides app building and deployment services and they will give you a free ( if not a little bit verbose ) URL for you to deploy client side code. The process is pretty easy and we can use a github repository to deploy our code continuously when we make changes to our source code.

After you create and account / Log in to the Netlify dashboard, there should be a tab called sites.

Clicking the sites tab will reveal a list of sites you have deployed on Netlify. From here you have two options:

Deploy using your static build directory created using the build script.
Connect your Netlify account to a git repository and use continuous deployment. This step requires that you commit your code to a git repository.

Deploying the static build directory is super simple but will require you to manually build and upload files to Netlify. Simply drag the build directory directly over the area at the bottom of the sites tab from the Netlify Dashboard.

This will automatically deploy your site to a url that Netlify will generate. Simple but requires work every time you update your source code.

On the far right side there will be a button that reads New site from Git. Selecting this option will walk you through the process of authorizing Netlify to access a code repository. After these steps are finished Netlify will build your site files from a build script you specify and deploy it automatically each time you make a commit to your repo!

Conclusion

Well that's it for me today. Happy hacking until we meet again :)

If you have any comments or questions about building apps with Cosmic JS, reach out to us on Twitter and join the conversation on Slack.

How to Build a Documentation App With Gatsby and Cosmic JS

Jacob Knaack — Sun, 17 Feb 2019 01:14:42 +0000

Documentation?... Documentation. Let’s say for a second that you want to create a way to easily publish and read docs, err… documentation. By the end of this read you will be able to do just that, all with the power of Gatsby (a static site generator) and Cosmic JS (an easy to setup and use Content Management System). Grab some coffee, find a comfy chair and let’s build something cool.

TL:DR

Gatsby Documentation App Demo
Check out the codebase

1.0 - Introduction

What is Gatsby?

Gatsby is an easy to use framework for generating static web site files. It comes bundled with all sorts of hotness, like React JS for building web components, and GraphQL for handling our component state without the need to configure something like Redux to handle external data.

What about Cosmic JS?

Cosmic JS will handle our publishing and data storage. It’s easy to set up and easy to implement for apps like this, yet scalable enough to handle more complex projects across larger teams. We will use this to create and store our documentation content. This will us allowing us to focus on how our users interact with our app, and let Cosmic JS do all the heavy lifting.

Is that all?

Well no… we are going to convert our docs from markdown to html, since that’s what web Browsers like. To do this we are going to use a package called Showdown, that can handle parsing and converting markdown to and from HTML.

Any Requirements?

Oh yeah, you will need to have access to a terminal, a Cosmic JS account with a bucket and a documentation object, and a recent(ish) version of Node JS installed on your machine in order to install the necessary software to make this app work. I’m going to be using yarn to run my build scripts but you can npm if you like. Just remember to choose one(npm or yarn) and stick with it as things can get little hairy when it’s time to deploy.

Let’s Build!!

1.1 - Setting up our Development Environment

To get started we will want to install Gatsby and install our dependencies. Easy peasy. Gatsby uses a handy command line interface (CLI) to build our initial project files. First we will want to install the CLI by installing it globally with npm:

$ npm install -g gatsby-cli

This gives us access to the gatsby command and allows us to initialize our project. Run the following script to create a new directory filled with a project template:

$ gatsby new gatsby-docs

Wait a second to allow the script to complete and you will notice a new directory created called gatsby-docs. Let’s see what’s inside by changing directories:

$ cd gatsby-docs

you should see a directory structure similar to this:

.
├── node_modules
├── src
├── .gitignore
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── gatsby-ssr.js
├── LICENSE
├── package-lock.json
├── package.json
└── README.md

Much of this will look familiar if are used to creating Node applications but some of this will be a little new. You should be able to get a development server up and running by executing the start script:

$ yarn start

After a second you should see a success prompt letting you know that everything has compiled properly and your app is live.

Now you can open up your browser pointing to localhost:8000 and see the compiled output. It should look something very similar to this:

Congrats! You have set up a working Gatsby site. But before we dig into what is going on under the covers let’s install the rest of our dependencies that will power our app:

$ yarn add cosmicjs showdown highlight.js dotenv node-sass gatsby-plugin-sass gatsby-source-graphql

Whoa... That’s a lot of newly installed packages, but each of these are super useful I swear.

cosmicjs will be used to add new content to our app.
showdown is the text parser I mentioned that will handle markdown and html conversion.
highlight.js is going to handle our syntax highlighting inside of our converted markdown text.
dotenv is an environment variable package that will make sure our sensitive tokens and/or runtime environment is configured from a .env file
node-sass and the gatsby-plugin-sass packages will allow to use .scss files to style our components.
gatsby-source-graphql will allow us to leverage GraphQL queries on external data (ie - use the Cosmic JS GraphQL api)

With all of that business out of the way we can look at our directory and configure our Gatsby source code to run properly.

2.0 - Configuring Gatsby

Now we can dig into our directory and make sure Gatsby is configured properly for using the technologies that will scalably and sensibly power our app.

The first file we will want to look into is gatsby-config.js. This file is used to configure high level plugins that allow any source code we write to be bundled properly when our static files are built. It also contains a little bit of metadata that describes our site to users and can be queried in our React Components.

Here we will add our newly installed plugins to the default configuration you see before you. First we just need to add gatsby-plugin-sass to the plugins list, allowing us to import sass files and leverage sass to write sensible styling specs for each component.

Next up we will add an object to end of our plugins list for gatsby-source-graphql that will configure our external GraphQL API endpoint to allow us to fetch data from Cosmic JS. Here’s how things should look:

Now we are set to make GraphQL queries to the Cosmic JS GraphQL API! Next, Let’s talk for a second about Gatsby and how things are going to break down.

2.1 Building our App with Gatsby

I’ve mentioned that Gatsby is a static site generator, but what does that mean? Gatsby takes all the fancy code we create and produces static files that are pre-configured using the config files we specify. By doing so we get increased performance for sites that may have lots of images, data to be fetched, and other assets that can slow down web applications.

Let’s now get some source code created. Our site is going to use just two ‘Pages’, one that will serve a home page to list the documentation we've created, and one for viewing a piece of documentation. But to fetch the content that we are going to display, we are going to use GraphQL, which we have recently configured. We will need to add some variables to our gatsby-node.js file in order to allow our static files to have the necessary parameters to make API calls.

Create a .env file and add your Cosmic JS environment variables

In your Cosmic JS Bucket > Basic Settings menu you will see fields for a bucket-slug and read and write keys down at the bottom. Copy all three of these things and add them to a .env file.

At your project root, type into your terminal:

$ touch .env

Now Create three lines:

We will use these with our dotenv package to allow our src files to access these variables when necessary.

Open up gatsby-node.js and add config variables to pages

We are now going to use Gatsby’s built in node API to give each page in our site access to the environment variable we just created. First we will import the variables from our .env file using dotenv, then we will explicitly set each variable in our page’s context. Your file should look like this:

Creating our first page

Now we are going to create our first page that will grab all of the documentation objects and display them at the root of our site, on index.js. First let’s create our list by creating a folder in the components directory titled docs - /src/components/docs/ and in that folder we will create a file titled index.js.

This will be our module that is first displayed when we render our page after fetching our docs. Here is the source code:

What's going on here

This page basically runs a big loop over our docs and returns some fancy jsx. We map through the docs array and produce a Link from Gatsby that contains the title, a date, and some content that uses a description for the piece of documentation that was published.

Feel free to add any .scss files to this directory as well to get a styling that works for you for the given class names.

Update the 'home' page with our new components

Now we can open up our home page file at /pages/index.js and import the components we just created and add them to our returned jsx.

Now any docs created on Cosmic JS, will appear here on the home page!

Notice the exported query at the bottom of the file. It contains two string type variable that will be present because we set the context object in our gatsby-node configuration.

With our newly created home page working, let’s create our doc view that will display content from the documentation that we post.

Creating our doc display page

Instead of adding a new file to the pages directory in Gatsby, we are going to create a templates directory and make a template page that we can configure on build, so that each time a doc is created, a new page can be created when we fetch our Docs from Cosmic JS.

Start by creating a templates directory at your project root, and then creating a docPage.js file within.

.
├── _templates
|   ├── docPage.js

Now add the page template complete with exported query that will fetch a singular doc from Cosmic JS.

Nothing will happen with this template until we tell Gatsby that it needs to create a page using this template. We do this so that Gatsby has a chance to fetch our Documentation from Cosmic JS before it builds the page using the necessary parameters for each GraphQL query at the bottom of docPage.js. We are using static site files after all.

Update Gatsby Node to build template pages

Let’s go ahead and add an export function to gatsby-node.js so that we are building docPage template from our GraphQL data:

Now when Gatsby creates its pages, ie - the index page will fetch our docs and create a page for each doc that is retrieved and attach all the necessary params to the page Content of each page. This way our template component is rendered and our GraphQL query should succeed!

3.0 Deployment

Lastly we can talk about deployment and about how static sites work. Deploying this bad boy can be a little tricky since this site uses a static build that won’t have the necessary pages of newly created docs until the deployment service has a chance to rebuild.

My recommendation is to use [netlify}(https://www.netlify.com/) and link your source from GitHub or wherever you store your code. From there you can trigger buildhooks in order to rebuild your site whenever certain events happen. Cosmic JS will allow a post request to be fired off at an endpoint when objects are created, deleted, edited, etc. So you can easily link the two together to make some magic happen. Keep in mind, if you want to allow users to create Docs from within your UI: you will need to fire off a POST request manually to activate a buildhook whenever a doc is successfully created.

Anyway, that’s all for me folks! Happy hacking.