Skip to Content
DocumentationSchemasGenerating schema types

Generating schema types

TwoTaps provides TypeScript type definitions for your schemas, making it easier to work with schema data in a type-safe manner. There are two ways to generate these types:

  1. Download from the Administration UI (recommended for quick access)
  2. Use the CLI tool (recommended for CI/CD pipelines and automated workflows)

Method 1: Download from the Administration UI

This is the quickest way to get your schema types. You can download them directly from the TwoTaps dashboard.

Go to your organization’s administration page and navigate to Schema Sets (/administration/schema-sets?organisationId=YOUR_ORG_ID).

Open the Context Menu

Find the schema set you want to generate types for, then click the three-dot menu (⋮) next to it.

Download Schema Types

Click on “Download schema types” from the menu.

This will download a schema.ts file containing TypeScript interfaces for all schemas in that schema set.

The downloaded file will be named schema.ts and will contain TypeScript interface definitions for all schemas in the selected schema set.

Method 2: Use the CLI Tool

For automated workflows, CI/CD pipelines, or when you need to regenerate types programmatically, you can use the TwoTaps CLI tool.

Prerequisites

You’ll need an API token to authenticate with the TwoTaps API.

Generate an API Token

  1. Navigate to your organization’s administration page
  2. Go to the API Token section: /administration/api-token?organisationId=YOUR_ORG_ID
  3. Click on “Generate New Token”
  4. Copy the generated token and store it securely

Keep your API token secure! Treat it like a password and never commit it to version control.

Set Up Environment Variable

Export the API token as an environment variable:

export API_TOKEN=your_api_token_here

The API token must be set as the API_TOKEN environment variable. The CLI tool reads this variable for authentication.

Run the CLI Command

The TwoTaps CLI is available through the @twotaps/site-utils-base package. You can run it using:

https://api-lb-prod.twotaps.io --orgName your-org-name --schemaWrapperName your-schema-set-name

This will generate a schema.ts file in your current directory.

Command Options

You can pass parameters via command line arguments:

Using organization name and schema set name:

export API_TOKEN=your_api_token_here
yarn twotaps generate:sdl \
  --twoTapsHost https://api-lb-prod.twotaps.io \
  --orgName your-organization-name \
  --schemaWrapperName your-schema-set-name

Using schema wrapper ID:

export API_TOKEN=your_api_token_here
yarn twotaps generate:sdl \
  --twoTapsHost https://api-lb-prod.twotaps.io \
  --ttSchemaWrapperId 123

Using the Generated Types

Once you have your schema.ts file, you can import and use the types in your code:

import { HeroBlock, LocationDetails, ContactForm } from './schema';
 
// Type-safe schema data
const hero: HeroBlock = {
  title: 'Welcome to our site',
  subtitle: 'Discover amazing content',
  backgroundImage: {
    url: 'https://example.com/hero.jpg',
    alt: 'Hero background',
  },
};

Integration with Site Utils

The generated types work seamlessly with the TwoTaps site utilities:

import { getPublicPage } from '@twotaps/site-utils-nextjs14';
import { HeroBlock } from './schema';
 
export async function getServerSideProps(context) {
  const page = await getPublicPage({
    slug: context.params.slug,
    preview: context.preview,
  });
 
  // Type-safe access to schema properties
  const heroBlock = page.revisionSchemas.find((schema) => schema.ttschema.name === 'HeroBlock');
 
  if (heroBlock) {
    const typedHero = heroBlock.properties as HeroBlock;
    console.log(typedHero.title); // TypeScript knows this exists!
  }
 
  return { props: { page } };
}

Best Practices

Tip: Regenerate your types whenever you make changes to your schema definitions in TwoTaps to keep them in sync.

For Development

  • Use the UI method for quick iterations and manual downloads
  • Keep the schema.ts file in your version control to share types across your team

For CI/CD

  • Use the CLI method in your build pipeline
  • Store the API token as a secret in your CI/CD environment
  • Add a step to regenerate types before building your application
# Example GitHub Actions workflow
- name: Generate Schema Types
  env:
    API_TOKEN: ${{ secrets.TWOTAPS_API_TOKEN }}
  run: |
    yarn twotaps generate:sdl --twoTapsHost https://api-lb-prod.twotaps.io --orgName your-org-name --schemaWrapperName your-schema-set-name

Version Control

Consider committing your generated schema.ts file to version control:

Pros:

  • Team members can work without needing API tokens
  • Faster builds (no need to fetch types every time)
  • Historical record of schema changes

Cons:

  • Types may become stale if not regenerated regularly
  • Merge conflicts if multiple people update schemas

A good compromise is to commit the types file but also regenerate it in your CI/CD pipeline to ensure it’s always up to date in production.

Troubleshooting

403 Forbidden Error

If you get a 403 error when using the CLI:

  • Verify your API token is correct and hasn’t expired
  • Check that you have the necessary permissions for the organization
  • Ensure the token is properly set in your environment variables

Types Don’t Match Schema

If your types seem outdated:

  1. Verify you’re using the correct schema set name
  2. Check that your schemas have been published in TwoTaps
  3. Regenerate the types to get the latest definitions

Missing Types

If some schema types are missing:

  • Ensure the schemas are part of the schema set you’re querying
  • Check that the schemas are not soft-deleted in TwoTaps
  • Verify the schema set ID or name is correct
Last updated on
Overview