create-package

name	create-package
description	Scaffold, build, and publish a new Datagrok package
when-to-use	When user asks to create a new package, scaffold a plugin, or start a new Datagrok project
context	fork
effort	high

Create a Datagrok Package

Help the user scaffold a new Datagrok package, add functions to it, build, and publish.

Usage

/create-package [package-name] [--test] [--js]

Instructions

1. Scaffold the package

Run from the directory where the package folder should be created:

grok create <PackageName> --test

• Package name must be PascalCase (e.g., TextStats, MyAnalysis).
• The --test flag adds a test scaffold. Use --js for plain JavaScript instead of TypeScript.
• After creation, install dependencies:

cd <PackageName>
npm install

2. Understand the package structure

The created package contains:

• src/package.ts -- main entry point for functions, viewers, panels, apps
• detectors.js -- semantic type detectors (loaded separately from the bundle)
• webpack.config.js -- webpack configuration (do not modify the externals)
• package.json -- metadata and dependencies

3. Add functions to the package

Functions are defined with annotation comments above the export. Common types:

Panel function (appears in context panel for matching data):

//name: MyPanel
//tags: panel, widgets
//input: string str {semType: text}
//output: widget result
export function myPanel(str: string) {
  return new DG.Widget(ui.divV([
    ui.divText('Result: ' + str.length)
  ]));
}

Add more function types via CLI:

grok add app <name>        # Application entry point
grok add viewer <name>     # Custom viewer
grok add detector <name>   # Semantic type detector

4. Build the package

npm run build

This runs grok api (auto-generates wrappers), grok check --soft (validates), and webpack (bundles). Do not modify the build script in package.json.

5. Publish the package

Publish to a configured server:

grok publish dev           # Debug mode (only visible to you)
grok publish dev --release # Release mode (visible to shared groups)

Return code 0 means success. After publishing in debug mode, find the package under Manage | Packages prefixed with v..

6. Share and release

• Share the package to user groups via right-click menu on the package in Manage | Packages.
• For public release: grok publish public --release.

Behavior

• Always ask for the package name if not provided.
• Use PascalCase for the package name.
• Default to TypeScript unless the user requests JavaScript.
• Include the --test flag unless the user says otherwise.
• After scaffolding, remind the user to run npm install.
• Follow Datagrok coding conventions: no excessive comments, no curly brackets for one-line if/for, catch/else-if on new line.
• When adding functions, use the annotation comment format (//name:, //tags:, //input:, //output:).
• Warn if webpack externals are modified (datagrok-api, rxjs, cash-dom, dayjs, wu, openchemlib/full are provided by the platform).