Once upon a time, the start of new development projects at Upstatement lead to tons of debate and soul searching around familiar questions: What build system should we use? What type of Sass architecture? Front-end framework? Template language? Deployment environment?

All important questions, no doubt. But all impediments to starting and seeing work take shape. It turns out that you sometimes don’t know which choice is the right one until you better understand the shape of the product. And the best way to understand the shape of the product is to start building it.

That’s why our web starter kit, Puppy, has been so crucial. It’s helped us power through those questions countless times since we first built it in 2015. We’re not the first people to discover the idea of a web starter kit, but we’re glad we established a system and product years ago that’s served us well.

As our work has grown more complex and more reliant on defining design systems, Puppy has become a delivery mechanism itself. We often turn over a set of Puppy pages as the end deliverable. Clients use this to integrate into their various systems and share with other stakeholders. Our humble web starter kit had become a presentation vehicle itself.

If Puppy was going to be used as a product to present and share our work, we realized it deserved its own product treatment. That’s why we’re excited to announce the release of Puppy 2.0.

Puppy’s default overview screen

The starter kit

At its core, Puppy is a lightweight tool for prototyping and sharing everything from a code sketch to a complete website.

When working inside of a system like Craft or WordPress, there are already default assumptions. But when everything is up for grabs, you can spend a lot of time grabbing. Puppy provides default assumptions and tools like:

  • Twig for templating
  • Gulp and Webpack for build orchestration and asset bundling
  • Babel for transpiling ES2015+ for today’s browsers
  • Sass and PostCSS for styles
  • ESLint and Prettier for consistent code style and formatting
  • Ava for testing

You can swap these out for different options of course (we do all the time). But having a starting place helps get things going with tools that everyone on a team is already familiar with.

You can use a mix of hard-coded and “live” data inside your prototypes. Inside the src/data directory you can place a JSON file with whatever data you want to display. For example, if you want to include a few sample articles — name this articles.json and place an array of article data. Inside any twig file, the articles object is available to you to use. Prefer to pull content from a remote API? Re-name that file to articles.js and export an async function that fetches and returns article data from your API at build time.

The novelty of Puppy isn’t so much in its feature set. Many of the core features are available in the countless static site generators that have emerged since Puppy’s inception. Its real value stems from its focus and simplicity. We’re not trying to solve every problem with Puppy, just the most common impediments to workflow and deliverables. Rather than hiding dependencies under abstractions that make it difficult to customize and extend, we expose them directly. It’s a starter kit, not a framework.

Puppy makes it easy to group different pages/views on the overview screen

Organize your work

Each HTML file contains a spot for metadata at the top. This front matter helps organize each page or screen. This includes spots for a title and an (optional) description, updated date, group, and thumbnail image.

Puppy uses the information you place here to build a simple directory at index.html with all of the pages. Ready for some magic? Use thumbnail: auto in the front matter for Puppy to automatically generate a thumbnail. You can also assign a group (ex: App Screens) to have it group those pages under their own section.

Puppy makes it easy to define your meta information

Share and deliver

We love Netlify and Puppy provides easy deployment to a Netlify site with the Netlify CLI. This makes it easy to share prototypes with clients and other partners (with password protection and other security considerations).

Using Puppy, we’re able to quickly start coding, organize and deliver work to the client for review and sharing. It helps give us a platform for building and collaborating so we can focus on the most creative and challenging part of every project. We’ve been using it in different iterations for nearly five years and we’re excited to share with the world. Interested in using it with your work?

  • Use the GitHub template to start your own project
  • Read the tutorial to help guide you along with your first project
  • Check out the demo site for a preview of what to expect

Further reading