Skip to main content

Gesso Starter Kit aka Baller Installer

The Gesso Starter Kit, also known as the Baller Installer, is a command-line utility that simplifies the process of creating new projects with various options such as design systems, frontends, CMS, and commerce platforms.

Prerequisites​

Before using the tool, make sure you have the following installed:

To install pnpm, follow the instructions provided in their installation guide.

Usage​

To create a new project, run the following command:

pnpm create @acromedia/gesso

The tool will prompt you to enter the following information:

  1. Project name: Enter the name of your project.
  2. Design System: Choose whether to create a design system project.
    • If yes, you'll be asked to provide your Figma token and Figma ID.
  3. Frontend: Choose whether to create a frontend project.
  4. CMS: Choose the desired Content Management System (CMS) for your project. You can select "None" if you don't want to use a CMS.
    • If you choose Drupal, you'll be asked whether to set up a Drupal backend.
  5. Commerce: Choose the desired Commerce platform for your project. You can select "None" if you don't want to use a commerce platform.
    • If you choose BigCommerce, you'll be asked to provide the BigCommerce X-Auth-Token, Store Hash, and Storefront URL.

Once you've provided all the necessary information, the tool will create the new project with the specified options.

CLI Arguments​

The following command-line arguments are available for use in the script:

General Options​

  • --skipMonoRepo: A boolean flag (true/false). Skips setting up a monorepo structure if true.
    • By default, the tool sets up a monorepo using TurboRepo if you've selected to createe a frontend and design system. you can skip this by setting --skipMonoRepo=true.

Design System​

  • --designSystem: A boolean flag (true/false). Specifies whether a design system is to be included in the project.

Figma Integration​

  • --figmaToken: A string. The personal access token to authenticate with the Figma API.
  • --figmaId: A string. The unique identifier for the Figma file to be used.

Frontend​

  • --frontend: A boolean flag (true/false). Specifies whether to set up a frontend application.
    • This option is required if you want to create a NextJS application.

Commerce Options​

  • --commerce: A string. Specifies the eCommerce platform being used (e.g., BigCommerce, Shopify).
  • --commerceUrl: A string. The base URL of the eCommerce platform.

BigCommerce Integration​

  • --bigCommerceXAuthToken: A string. The authentication token for BigCommerce API access.
  • --bigCommerceStoreHash: A string. The store hash value for BigCommerce, used in API calls.
  • --bigCommerceStorefrontUrl: A string. The URL for the BigCommerce storefront.

Shopify Integration​

  • --shopifyStoreDomain: A string. The domain name of the Shopify store.
  • --shopifyAccessToken: A string. The access token for authenticating with the Shopify storefront.
  • --shopifyAdminAccessToken: A string. The admin access token for Shopify's API.

ERP Options​

  • --erp: A string. Specifies the ERP platform being integrated (e.g., Acumatica).

Acumatica Integration​

  • --acumaticaUsername: A string. The username for Acumatica authentication.
  • --acumaticaPassword: A string. The password for Acumatica authentication.
  • --acumaticaClientId: A string. The client ID for Acumatica OAuth authentication.
  • --acumaticaClientSecret: A string. The client secret for Acumatica OAuth authentication.
  • --acumaticaUrl: A string. The base URL for the Acumatica instance.

CMS Options​

  • --cms: A string. Specifies the CMS being used (e.g., Storyblok, Contentful).
  • --cmsBackend: A boolean flag (true/false). Indicates whether a CMS backend should be set up.
  • --cmsPreviewSecret: A string. The secret key for enabling CMS preview mode.
  • --cmsUrl: A string. The base URL of the CMS being used.

Storyblok Integration​

  • --storyblokAccessToken: A string. The access token for Storyblok API.
  • --storyVersion: A string. Specifies the version of the Storyblok content to fetch (draft or published).
    • Draft if necessary for Storyblok's preview mode to render draft content.

GitLab Integration​

  • --gitlabToken: A string. The access token for interacting with GitLab APIs. Necessary for creation of .npmrc file.
    • Without this token, the .npmrc file will not be created, and you will need to manually add the GitLab token to the file. Packages will not be able to be installed from the GitLab registry without this token.
    • Used in frontend setup, and CMS "Drupal" setup"

Local Development Options​

  • --useLocal: A boolean flag (true/false). Specifies whether to use local gesso packages instead of remote packages.

Customizing Project Creation​

You can also provide options directly in the command line to skip the interactive prompts. For example:

pnpm create @acromedia/gesso --designSystem=true --frontend=true --cms=Drupal

This command will create a new project with a design system, frontend, and Drupal as the CMS. If you provide all required options in the command line, the tool will not prompt you for any additional information.

Stories​

Stories that link to all the Gesso provided stories are automatically created in your design-system src/stories/gesso

  • If you don't want some or all of the stories, just delete the associated files.
  • You can edit the files and still recieve upstream changes, as they are published exports, not copies.
  • Updates will happen automatically when you update your Gesso version, although if you wish to get new stories, you will need to run pnpm gesso generate-stores or manually create the missing files.

Create Gesso

A CLI tool to create new Gesso projects with various configurations.

Usage​

pnpm create @acromedia/gesso my-project

Configuration​

The CLI supports configuration through command-line arguments, environment variables, and a configuration file. This makes it easier to set up projects with predefined settings.

Configuration File​

You can create a configuration file to pre-populate options. The script will look for the following files in your home directory and if not found will check your current directory:

  • .create-gesso.json
  • create-gesso.json

Example configuration file (.create-gesso.json):

Note: Omit any values you want the script to prompt you for such as project.name or cms.type This is useful for gesso development when you still want to set the name, or select cms.type

{
  "project": {
    "name": "my-project",
    "designSystem": true,
    "frontend": true,
    "skipMonoRepo": false
  },
  "figma": {
    "token": "your-figma-token",
    "id": "your-figma-file-id"
  },
  "cms": {
    "type": "storyblok",
    "backend": false
  },
  "storyblok": {
    "url": "https://gapi.storyblok.com/api/v1",
    "previewSecret": "your-preview-secret",
    "accessToken": "your-access-token",
    "oAuthToken": "your-oauth-token",
    "region": "eu",
    "spaceId": "your-space-id",
    "storyVersion": "published"
  },
  "drupal": {
    "url": "https://your-drupal-site.com",
    "previewSecret": "your-preview-secret"
  },
  "commerce": {
    "type": "shopify"
  },
  "shopify": {
    "storeDomain": "your-store.myshopify.com",
    "accessToken": "your-access-token",
    "adminAccessToken": "your-admin-token"
  },
  "bigcommerce": {
    "xAuthToken": "your-x-auth-token",
    "storeHash": "your-store-hash",
    "storefrontUrl": "https://your-store.mybigcommerce.com"
  },
  "drupalCommerce": {
    "url": "https://your-drupal-commerce-site.com"
  },
  "erp": {
    "type": "acumatica"
  },
  "acumatica": {
    "username": "your-username",
    "password": "your-password",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "url": "https://your-acumatica-instance.com"
  },
  "gessoAI": {
    "type": "gemini"
  },
  "gemini": {
    "apiKey": "your-gemini-api-key"
  },
  "local": {
    "url": "http://localhost:3000"
  },
  "gitlab": {
    "token": "your-gitlab-token"
  },
  "useLocal": false
}

Available Configuration Options​

Project Options​

  • project.name: Project name
  • project.designSystem: Whether to create a design system project
  • project.frontend: Whether to create a frontend project
  • project.skipMonoRepo: Whether to skip monorepo setup

Figma Integration​

  • figma.token: Figma access token
  • figma.id: Figma file ID

CMS Options​

  • cms.type: CMS type ('drupal', 'storyblok', 'generic', or undefined)
  • cms.backend: Whether to set up a CMS backend
Drupal-specific Options​
  • drupal.url: Drupal site URL
  • drupal.previewSecret: Drupal preview secret
Storyblok-specific Options​
  • storyblok.url: Storyblok API URL
  • storyblok.previewSecret: Storyblok preview secret
  • storyblok.accessToken: Storyblok access token
  • storyblok.oAuthToken: Storyblok OAuth token
  • storyblok.region: Storyblok region
  • storyblok.spaceId: Storyblok space ID
  • storyblok.storyVersion: Storyblok story version

Commerce Options​

  • commerce.type: Commerce platform type ('acumatica', 'bigcommerce', 'shopify', 'drupal-commerce', 'generic', or undefined)
Shopify Options​
  • shopify.storeDomain: Shopify store domain
  • shopify.accessToken: Shopify access token
  • shopify.adminAccessToken: Shopify admin access token
BigCommerce Options​
  • bigcommerce.xAuthToken: BigCommerce X-Auth-Token
  • bigcommerce.storeHash: BigCommerce store hash
  • bigcommerce.storefrontUrl: BigCommerce storefront URL
Drupal Commerce Options​
  • drupalCommerce.url: Drupal Commerce site URL

ERP Options​

  • erp.type: ERP platform type ('acumatica' or undefined)
Acumatica Options​
  • acumatica.username: Acumatica username
  • acumatica.password: Acumatica password
  • acumatica.clientId: Acumatica client ID
  • acumatica.clientSecret: Acumatica client secret
  • acumatica.url: Acumatica instance URL

Gesso AI Options​

  • gessoAI.enabled: Whether to enable Gesso AI
  • gessoAI.geminiAPIKey: Gemini API key

Local Development​

  • local.url: Local development URL

GitLab Integration​

  • gitlab.token: GitLab personal access token

General Options​

  • useLocal: Whether to use local packages

How Configuration Works with Prompts​

The configuration file works in conjunction with the interactive prompts:

  1. Defaults: Values specified in the config file serve as defaults
  2. Prompt Behavior:
    • If a value is specified in the config, the prompt will be skipped
    • If a value is not specified, the prompt will be shown
  3. Choices: For options with predefined choices (like CMS type), the config value must match one of the available options
  4. Credentials: Sensitive information like tokens and secrets can be pre-populated from the config file

Config File Version​

The version field in the config file is required and serves several important purposes:

  1. Format Validation: Ensures the config file follows the expected structure
  2. Future Compatibility: Allows for handling different versions of the config format
  3. Breaking Changes: Enables the CLI to handle breaking changes in the config format gracefully

The current supported version is "1.0.0". The CLI will validate and handle the config file according to its version to ensure backward compatibility while allowing for future improvements.

Command Line Arguments​

You can override any configuration file settings using command-line arguments:

pnpm create @acromedia/gesso my-project --cms drupal

Environment Variables​

You can also set configuration values using environment variables. The CLI will look for environment variables with the GESSO_ prefix:

export GESSO_CMS_TYPE=drupal
export GESSO_CMS_BACKEND=true
export GESSO_FIGMA_TOKEN=your-figma-token

Priority Order​

  1. Command-line arguments (highest priority)
  2. Environment variables
  3. Configuration file
  4. Default values (lowest priority)

Disabling Configuration File​

To disable the configuration file and use only command-line arguments or environment variables:

--no-config

Specifying a Custom Config File​

To use a custom configuration file:

--config ./custom-config.json

Available Options​

Project Options​

  • --projectName: Name of your project
  • --designSystem: Whether to create a design system project
  • --frontend: Whether to create a frontend project
  • --skipMonoRepo: Whether to skip monorepo setup

CMS Options​

  • --cms: CMS type (drupal, storyblok, generic, none)
  • --cmsBackend: Whether to set up a CMS backend
  • --cmsUrl: URL of an existing CMS
  • --cmsPreviewSecret: Preview secret for CMS

Commerce Options​

  • --commerce: Commerce type (acumatica, bigcommerce, shopify, drupal-commerce, generic)
  • --commerceUrl: URL of the commerce system

ERP Options​

  • --erp: ERP type (acumatica)

Gesso AI Options​

  • --gessoAI: Whether to enable Gesso AI
  • --geminiAPIKey: API key for Gemini

Local Development​

  • --localUrl: Local development URL
  • --useLocal: Whether to use local packages

Storyblok Options​

  • --storyblokAccessToken: Storyblok access token
  • --storyblokOAuthToken: Storyblok OAuth token
  • --storyblokRegion: Storyblok region
  • --storyblokSpaceId: Storyblok space ID

GitLab Options​

  • --gitlabToken: GitLab access token

Examples​

Basic Project​

pnpm create @acromedia/gesso my-project

With Design System​

pnpm create @acromedia/gesso my-project --designSystem --figmaToken your-token --figmaId your-id

With CMS​

pnpm create @acromedia/gesso my-project --cms drupal --cmsBackend