The Can-Do’s of CodePen Projects

We just recently launched Projects, the latest big feature over on CodePen. It's quite a bit different than the Pen Editor, so let's take a look at all the things it can do!

A Complete File System, and Complete HTML Files

With CodePen Projects, you get a sidebar of files for you to put whatever files you like.

That's different than the Pen Editor on CodePen, which only gives you the HTML, CSS, and JavaScript editor to work with. While that's super convenient for many types of demos, it can be limiting. What if you need multiple HTML files to link between? What if you need partials to include as needed? What if you need to upload other files to work with just for this demo?

With Projects, you have complete control over the entire file structure. Create files and folders as needed. HTML files are complete documents, so you aren't limited to our boilerplate HTML structure like you are in the Pen Editor.

Drag and Drop Uploading

If you have file on your local machine that you'd like to upload and work with on CodePen, it couldn't be easier. The sidebar of a Project is drag-and-drop ready!

This makes it easy, for example, to export a repo and move it over to CodePen to play with. These files could be HTML, CSS, JavaScript, any of the preprocessor types we support, images, fonts, and lots of other types of assets. It does limit the upload of some file types (for example, back-end languages like PHP) to make clear what CodePen Projects does and doesn't support.

Process Sass (or many other Preprocessors) with Partials

Do you like to keep your variable declarations in a separate file? Perhaps you break out your layout CSS into its own file as well. Working with partials is a super useful part of any CSS preprocessor!

This is an example of how I like to work:

You can view the compiled version by opening the "processed" file in the sidebar. It prevents you from editing the processed file though, as you'd lose changes next time the preprocessor compiled.

Build Multi-Page sites with HTML Includes

CodePen Projects offers two preprocessing languages that can do HTML includes: Pug and Nunjucks.

In Pug, you use include file.pug (where `file.pug` is the file path to any other Pug file) and it will grab that file and include it.

This makes it easy to piece together parts of files into complete HTML documents, making multi-page sites much easier. You can also weave together HTML using the block syntax which allows you to make a template in which any file "extending" it can pass in chunks of content that will replace those areas.

In Nunjucks, the syntax is like {% include "components/mini-header.njk" %}, and works exactly the same way. It goes and gets that file and plunks it into place in the file that called it. Nunjucks isn't whitespace-dependent like Pug either, it's just an extension of regular HTML.

Make a Pattern Library with Nunjucks

This one probably deserves and entire article (soon!), but speaking of Nunjucks, Nunjucks has the concept of a "Macro", which is a bit like an include, only you can pass parameters to it. It's a wonderfully simple syntax:

Now let's say you want to load up that Macro and use it elsewhere.

{% import "pattern/_colors.njk" as macroColors %}

Say we're building out color swatches for our pattern library. We can define the colors (with notes) as an array, then loop through it, calling the Macro with the data.

That's powerful stuff! Call this HTML, passing these parameters, and sprinkle those parameters through the HTML however I need them. That could be useful for all kinds of stuff. Imagine a modal dialog, in which you need to pass in the header and content, but also classes to define the style, or values to determine if certain buttons should show or not.

Use ES6 Includes via Webpack

Let's say I have a little helper function that you pass a string of HTML and it returns a real DOM node. In ES6, we can export a function like that so that other JavaScript files can import it as a dependency:

export function getNodes(str) { 
  return new DOMParser().parseFromString(str, 'text/html').body.childNodes;
}

Then in any file that wants to use it:

import { getNodes } from "./helpers";

That's just starting to land natively in browsers, but for the most part, that kind of thing is handled by Webpack bundling it all up. And that's also generally paired with Babel, so you can go all-in on the ES6 syntax.

You're free to work either way in CodePen Projects. Leave it alone if you want the browsers to do things natively, or flip the switch and turn on Webpack and Babel processing:

You can write in Typescript as well. We've seen some fancy-dancing using SystemJS with Typescript and ultimately importing dependencies right off npm.

Auto-formatted Markdown

Does your project have a README? Perhaps a TODO list for yourself? Not only can you write in Markdown with CodePen Projects, but the preview window will apply some style to it so you can look at it in a format much like any other blog post on CodePen.

You can also open the processed version of the file to see the processed HTML without any other influence.

Have a Development version and Deployed version of your Project

At any time, you can click the Deploy and open up this dialog which allows you to deploy your Project out to a special URL:

That is a public URL that you can share with anyone. It has zero CodePen UI or influence whatsoever. It's just a straight up copy of your files, hosted for the world to see. You can use it for testing, showing clients, or whatever you like.

An important bit here is that the works just like real world deployment does. You can continue to work on your Project, saving it and changing it to your heart's content, and that doesn't affect the deployed version. It becomes your development version, effectively. Then, again at any time, you can deploy.

There are no limits to how many times you deploy, only how many different Projects you have deployed.

Use a Custom Domain Name for your Project

You probably noticed the URL is a little funky for deployed websites. We hope someday we'll allow you to customize that, but what is here today (and even better really) is the ability to use a custom domain (that you own) to point to your deployed Project.

It's a matter of changing DNS "A Records" (documentation) to point to a couple of special IP addresses we've set up for this.

After that propagates and I've deployed, my Project is available at my custom domain!

Notice that example is HTTPS. That doesn't come automatically, but in this case I've set up CloudFlare, changed my domain's nameservers to point to CloudFlare, then the A Records at Cloudflare to point to the CodePen IP's. Free HTTPS! Which means I can do stuff like use modern JavaScript stuff that requires HTTPS, like getUserMedia or register a Service Worker.

Use Vim Key Bindings

Sure can. It's a user setting on CodePen that follows you into all the different editors. You can pick key bindings that mimic Sublime Text too, if you're partial to that.

I point this out as just one tiny little comfort feature of working on CodePen. There are so many others, like:

  • Autocomplete
  • Emmet
  • Choice of syntax highlighting theme
  • Choice of tabs/spaces and how deep
  • Choice of font and size
  • Line wrapping (or not)
  • Line numbers (or not)
  • Matching brackets (or not)
  • And the list goes on! Lots of options for setting up the code editor just how you like

Start with a Template

When you kick off a brand new Project, we've prefilled the sidebar with a bunch of choices:

By no means do you have to pick a template from this list, but it might help you get a feel for things or speed things up if what you want to build uses these technologies. We're hoping to have lots of templates, eventually, for you to get started with. If you have an interesting one you've built, let us know!

You can also easily build your own templates. On any Project, flip on the template toggle in settings:

Now that template is available whenever you start a new Project:

And of course... any public Project you find on CodePen you can fork!

... and (wait for it) So Much More

Here's an incomplete list of things I didn't get a chance to tell you about: searching for external assets, tidying your code, analyzing your code, exporting, sharing (gasps for air), global assets, keyboard shortcuts, or all the different views!

I'll leave you by encourging you to check out our landing page for Projects and checking out the documentation.