Yesterday ZappJS was announced to the world and I’m extremely thankful for the overwhelming response it’s received in the past 24 hours.
It has taken many years, iterations, incarnations, reincarnations and cups of coffee to create ZappJS. My hope is that it will become a valuable resource to the development community.
Before I go on, I’d like to take a moment to graciously thank my wife Crystal, our two pups, and our friends & family for supporting me through this journey and always believing in me. I’m truely and eternally grateful.
So… What Exactly Is ZappJS?
ZappJS is a spec-driven code generator for building frontend and backend applications at lightning speed — and with higher accuracy.
But what do these buzzwords mean? Let’s break them down into two topics:
- Specs
- and Generators.
Specs
To understand ZappJS is to first understand the concept of “speccing” — a method of describing various parts of your application that requires coding, documentation, diagrams or other generated artifacts.
There are many different types of specs — some of which are described below.
Model-Driven Specs
Traditionally, specs have been widely used to describe various system designs with languages and tools like UML, ERD and Flow Charts. These specs describe core business logic such as software architecture, entity relationships, workflows and algorithms. Modeling tools were primarily used to produce documentation and diagrams to help visualize system designs.
API-Driven Specs
Recently, specs have been made even more popular by Swagger, RAML, Apiary and API Blueprint — all of which are used to describe APIs.
These specs are generally written with markup (Blueprint, Markdown) or object notation (JSON, YAML) to generate API documentation, client-side libraries, server mocks — and in some cases, even real API code.
Generator-Driven Specs
With ZappJS, Specs can be used to describe anything. Models, APIs, Views, Controllers, Build Configurations, Package Managers, CLI Programs, System Designs, Web Architectures; you name it.
Generators ultimately determine which specs you write in ZappJS. They depend on Templates, Engines, Schemas and Files to generate unique code based on your Specs.
- Templates implement various design patterns and defines what your Specs will look like
- Engines processes and renders templates
- Schemas validate your spec
- Files brings Templates, Engines and Schemas together; passes Specs through each to generate unique source code; and defines the destination directories and files of the source code
Pro Tip: Templates should implement common design patterns, so that the corresponding specs feel familar as you write them. In return, you should have some understanding of what code is being generated .
There is no mandatory structure to Specs. It is based on the author’s choices of design patterns and coding styles. With that said, generators can be modeled after Swagger, RAML and other specifications to help keep your specs consistent with industry standards.
What Do ZappJS Specs Look Like?
ZappJS specs are written with our editor (available online, and for macOS, Windows & Linux). Add, edit, remove and explore you specs in many ways.
Specs in ZappJS can be very high level or low level depending on your needs. They can be used to describe code that is generated for one file (as above) or many:
Depending on the generators you choose, ZappJS can offer suggestions and even auto-complete new specs as you type. This makes it easier to know which specs are available for your generators, and helps you follow the design patterns they want you to implement.
For example, if you’re using a React generator, you might expect the ability to add props to a component:
However, that might not always be the case. You might want to implement these patterns a different way or not at all. In that case, you could try another generator or create your own (we’ll get to that later).
In general, the goal should be to use basic object notation as much as possible to describe your application — strings, numbers, arrays, objects, booleans and null:
However, in some cases you might want to mix in manual code alongside generated code:
Other speccing features include:
- Tree View displays object specs, so you can drill down to a specific area
- Drag-and-drop to rearrange specs
- Validation via Schemas
Generators
The other half to ZappJS as a spec-driven code generation platform is, of course, code generation.
Code generation comes in many forms. ZappJS is meant to generate source code that you would normally write by hand — before it’s compiled (or transpiled).
This allows you to see how your specs are being interpreted by your generators, to inspect the generated code for issues, and to ensure the overall quality of the code remains very high.
But Where Does Code Generation Come From?
Code generation can either be 1) added directly to a project, 2) imported from other projects, or 3) a combination of both.
To add generation to any project you will need: Templates, Schemas, Configs and Engines.
To import another generator, you will only need: Imports.
Imports
Importing generators is the easiest way to add code generation to your project. You can add popular generators to your project and instantly gain access to new specs and automatically generate code files. As you add more generators, more specs become available.
In order to add an import to your project, click the + button at the bottom of the screen to display a list of generators you can import:
Select a generator and it will (likely) generate some basic code right away and appear next to the + button:
If you click on the + button in the spec editor, you will see which specs are now available:
You can continue adding generators to make more specs available and generate additional code.
From here, you can keep working on your project, or learn how to create your own generators below.
Templates
Generating your own code is highly recommended. It helps you stay connected to your generators and provides code satisfaction, because you get to decide which design patterns and coding styles to use.
Templates can be written in any templating language, but require an Engine to render them.
To create a template, go to the Templates section, click the + button, name the template readme and press enter:
Click the + button next to the readme spec and enter template as the <key> and # {{name}} as the <value> (this is a simple Handlebars template), and press enter:
Congrats! Your readme template is complete 📝
Engines
In order to process your template, your generator needs a template engine.
When you’re first using ZappJS, you’ll probably want to import another generator that has an Engine you want to use for your project.
The most popular engines are:
If you are feeling adventurous and want to try making your own engine using JavaScript, follow the instructions below. Otherwise, import the zappjs/handlebars generator to your project and continue to Files.
These instructions show how to create a very basic engine that simply finds and replaces variables in braces (i.e {{name}}).
Go to the Engines section, click the + button, name the engine handlebars, press enter:
Then click + next to handlebars to add JavaScript engine code that will handle the parsing:
export default function engine(specs, template) {
return template.replace(/{{([a-z0-9]+)}}/g, (match, name) => {
return specs[name] || '';
});
}It should look like this:
Your engine will be loaded into the ZappJS code generation platform and available to use in Files.
Pro Tip: Ideally you want to use an existing template engine library that you wrap inside of this function via scripts:
To see a more advanced version, please check out the zappjs/handlebars generator.
But if you’re happy with your engine, keep chuggin’ 🚂
Schemas
A crucial part to the speccing experience is validation and prediction. That’s where schemas come in.
Schemas define how a spec should be written. They help with suggesting specs as well as providing errors when specs are invalid.
Go to Schemas, click the + button, enter app and press enter:
Click + next to app and set its type to object:
Next add properties with a name under app like this:
Finally, add a description and type to your name property:
Schemas pass validation, for now ✅
Files
Now you need to specify which file(s) you would like to generate.
Go to the Files section, click the + button, add a file named README.md, and press enter:
Next click + next to README.md and add the following fields:
- engine: handlebars
- template: readme
Like this:
Finally, add mapping and map from the /app/name spec (we will add this next) to name (the variable we used in our template):
Files all set 📁
I think we’re ready to…
Generate Some Code ⚡️
Now that you’ve added a Template, Engine, Schema and File; you just need to trigger your generator by adding some Specs.
Go to Specs and click the + button:
What?! How did that get there??
…Oh! I know!! This spec what suggested by our very own Schemas 💥
Select app from the suggestions, then click + to get…you guessed it: another suggestion! (did you guess it?)
This spec was also suggested by your Schemas!! Pure magic. Yet practical. 🔮
Okay, sorry, whew. Gets me every time 🙈
*Ahem* Select name and enter a name for your application.
Then — as soon as you press enter — you should finally see… your first… generated… README.md f..
[insert air horn] 🚨 BWWAAA BWAA BWWWAAAAAAAAAAAAAAAAA 🚨
You did it! 🎉
Now go ahead and celebrate by going to our generators page and getting inspired.
For something more advanced, we highly recommend checking out this generator: zappjs/react (view example usage here)
Pro Tip: you can combine generators to generate multiple aspects of your project. In fact, some generators even share the same spec, so when you update your app’s version, for example, it can write to several files (i.e package.json, README.md, LICENSE, etc.)
Conclusion
ZappJS is a robust development tool. This walkthrough provides a small sample of the what ZappJS has to offer, but there will be many more guides, docs and videos to come.
Thank you so much for taking the time to learn about ZappJS.
♥️ Chris
