Create a Charge Application That Builds and Deploys with Now

Charge is an opinionated, zero-config static site generator written in JavaScript. Charge is fast, simple and behaves the way you expect it to.

In this guide, we will walk you through creating and deploying a basic Charge website with ZEIT Now.

Step 1: Set Up Your Charge Project

Charge focuses on simplicity and provides no boilerplate as a result. To get started with Charge create your project directory, let's call it charge-app, and cd into it:

Creating and entering into the /charge-app directory.

Next, initialize the project:

Initializing the project, this creates a package.json file.

Yarn will present some initial questions to set up your project, complete this and when done, add Charge as a development dependency:

Adding Charge as a development dependency to our project.

Now, make an addition to package.json, as recommended by the Charge documentation, by adding the following scripts object:

{
  "scripts": {
    "now-dev": "charge serve src",
    "build": "charge build src dist"
  }
}

Adding development and build scripts to the package.json file.

These scripts enable you to run a local development server with now dev and, as you will see later on, build your Charge site before deploying with now.

The @now/static-build Builder supports a custom now-dev script that allows you to define custom development behavior while gaining extra features that mimic the Now platform locally.

Step 2: Add Content To Your Charge Project

The following example content setup demonstrates a few of Charge's key features, notably the use of .jsx, .mdx, and using a layout component.

Firstly, create two directories, /src and /src/pages within your project directory:

Creating a /src directory with a /pages directory inside of it.

By keeping your components inside of the /src directory and our content inside of the /pages directory, this will help keep your project organized.

Next, create an index.html.jsx file inside the /src directory that will serve as the entrypoint to your Charge-powered website.

Now, you will need to add some some content to your index file. Use the example below, or add your own:

export default () => {
  return <h1>Welcome to my new Charge site!</h1>
}

An example index.html.jsx file in a Charge project.

Like many static site generators, Charge encourages the use of a layout component. This component will be used to define the layout of your .mdx pages later on.

Create a simple layout.html.jsx file inside of the /src directory with the following content:

export default ({ children }) => {
  return children
}

An example layout.html.jsx file in a Charge project.

If, at any point, you want to see how your changes look, you can serve them locally with the script you added in the first step:

Starting up a local development server using a script.

Charge will open a new tab for you, if not you can navigate to localhost:2468 to see the changes you make, live-reloading is enabled through Browsersync.

Now that you have a layout component, use it to wrap a .mdx file. Create a file named about.html.mdx inside of your /pages directory.

Add some content to your about page and export it inside of the layout component you created above. Your about.html.mdx should look similar to this:

import Layout from '../layout.html.jsx'

Everything between the import and export in the source is **just markdown** using [MDX](https://mdxjs.com/)!

export default ({ children }) => <Layout>{children}</Layout>

An example about.html.mdx file in a Charge project.

Before deploying your project, import the about page you just created by modifying your index.html.jsx to look like this:

import About from './pages/about.html.mdx'

export default () => {
  return (
    <>
      <h1>Welcome to my new Charge site!</h1>
      <About />
    </>
  )
}

An example index.html.jsx file in a Charge project that imports the About content component and uses it in the page.

Now that you have a simple Charge site created, you're ready to deploy with Now.

Step 3: Deploy Your Charge Project with Now

To deploy with Now, you will need to provide a small amount of instructions on how to build your Charge project using a now.json configuration file at the root of your project directory.

Create a now.json file at the project root and add the following code:

{
  "version": 2,
  "name": "my-charge-project",
  "builds": [
    {
      "src": "package.json",
      "use": "@now/static-build"
    }
  ]
}

An example now.json file in a Charge project.

The now.json file allows you to achieve many things with your deployment, below is a description of what each property does:

• version ensures you are using the latest Now 2.0 platform version

• name defines a project name your deployment will be known by under Now

• builds provides one build step using @now/static-build to instruct Now to statically build the project and deploy the dist directory, using the package.json file as an entrypoint

  Note: By default, Now will cache static assets in every region, making your site fast to load wherever you are in the world.

Lastly, add a now-build script to package.json which will be used by the Builder, @now/static-build, to specify what command Now should run to build the site in the cloud:

{
  "scripts": {
    ...
    "now-build": "yarn build"
  }
}

Adding a now-build script to the package.json file in a Charge project.

Additionally, to speed up the deployment process by not uploading un-necessary files, create a .nowignore file at the root of the project:

There are three items, in this example, that you should add to the .nowignore file; /node_modules, /dist, and/tmp - the directory Charge creates when serving content locally:

node_modules
tmp
dist

An example .nowignore file in a Charge project.

Finally, deploy the application with Now.

If you have not yet installed Now, you can do so by installing the Now Desktop app which installs Now CLI automatically, or by installing Now CLI directly.

Now allows you to deploy your project from the terminal with just one command:

Deploying an application with Now using only one command.

You will see a short build step in your terminal followed by the news that your Charge project has now been deployed, it should look similar to this: https://charge-example.now.sh/

Bonus: Omitting the .html Extension

Your Charge site is now deployed, but wouldn't it be great if the URL didn't show the file extension at the end?

Thankfully, Now provides an easy method to achieve this, simply add the following code to your package.json file:

{
  ...
  "routes": [{ "src": "/(.*).html", "dest": "/$1" }]
}

In this example, routes is used to rewrite paths, meaning that the .html extension will no longer be displayed.

Resources

For more information on working with Charge, please refer to their documentation.

To configure Now further, please see these additional topics and guides: