ZappJS

Specs (Specifications)

Specifications (or "Specs") are the heart of the Zapp code generation lifecycle. Specs are the instructions that guide the Generators in creating the code you need. They determine the logic, structure, and even metadata for the generated code. This section aims to provide a comprehensive understanding of how to work with Specs in Zapp effectively.

What Are Specs?

Specs are configuration files or code snippets that capture the requirements for the code you want to generate. These can define anything from the architecture of an application, to database schema, to individual class and function implementations.

The primary use cases for Specs include:

• Defining application architecture and logic.
• Specifying data models and their relationships.
• Declaring configuration or environment variables.
• Setting up code design patterns and reusable modules.

Creating Specs

Creating Specs is the first step in using Zapp for your project. The Specs can be written in TypeScript and will soon support JSON, YAML, and other formats. Here's a basic example in TypeScript:

import { MyApiZapp } from '@/zapps/MyApiZapp';

export default ServiceZapp({
  name: 'my-api',
  models: {
    user: {
      type: 'string',
    },
  },
});

In this example, the Spec defines a data model with its fields and a controller with its actions.

Built-in and Custom Specs

Zapp provides some built-in Specs to get you started quickly. These cover common scenarios like CRUD operations, RESTful APIs, or MVC architectures. However, you can also create custom Specs tailored for your specific requirements.

Validating Specs with Schemas

To ensure the integrity and correctness of Specs, Zapp uses Schemas based on JSON Schema. These Schemas validate the Spec files to ensure they meet the required format and contain the necessary attributes.

Organizing Specs in Zapps

In a typical Zapp project, you may have multiple Specs for different aspects of your application. These Specs can be organized under a single Zapp for better modularity and easier management.

Best Practices

When working with Specs in Zapp, consider the following best practices:

• Keep your Specs as modular and focused as possible.
• Use Schemas to validate Specs rigorously for consistency and integrity.
• Continuously update Specs as your project requirements evolve to keep the generated code up-to-date.

By mastering Specs, you take a significant step toward leveraging Zapp's full potential in automating your code generation process, thereby keeping your project agile and maintainable.