Feat: CLI: Improve Developer UI Launch Experience with Sensible Defaults in JS

[chrisraygill]

Feedback requested: Proposal to improve the Developer UI launch experience

Problem 1:

The current method for launching the Genkit Developer UI requires users to explicitly specify the command to run their application code. This approach, while very flexible, is very verbose and can be intimidating to new users. In the JS ecosystem, there are many ways to run your code, so example of launching the Developer UI inclide:

# Running a typical development server
npx genkit start -- npm run dev

# Running a TypeScript file directly
npx genkit start -- npx tsx --watch src/index.ts

# Running a JavaScript file directly
npx genkit start -- node --watch src/index.js

This explicit approach is overly verbose and can look intimidating to new users.

Problem 2:

The current approach makes it much more cumbersome to run other genkit CLI commands such as flow:run or eval:flow. Today, you have to start the Genkit server first by running genkit start --no-ui -- <run code cmd>, then open a new terminal instance to run the CLI commands. This is very cumbersome and not intutive.

Proposed Solution 1

We should introduce sensible defaults for the genkit start command while retaining the flexibility to customize the app launch command. Here's the proposal:

When a developer runs genkit start, we will automatically look for the following scripts in the package.json in priority order:

1. dev:genkit script: When a dev:genkit script is available, running genkit start will be the equivalent of running genkit start -- npm run dev:genkit.
2. dev script: When a dev:genkit script is not present but a dev script is, then running genkit start will be the equivalent of running genkit start -- npm run dev.

Note: I'm proposing dev instead of start, another common script to run app code, because dev is more likely to be used for running code in a debug mode with --watch which is needed for the DevUI to have hot-reload.

We will still keep the option to do genkit start -- <manual cmd>, but will start our tooling docs by recommending that developers add a dev:genkit script to their package.json for the best developer experience.

Pros:

• I believe this is the most idiomatic JavaScript solution by leveraging the package.json for scripts to run app code. Doesn't require any new config files.
• Many developer will already have a dev script that will work well.

Cons:

• This is JS-specific, so the same approach won't work across languages (Go, Python). A different solution will be needed for those runtimes which will introduce more maintenance burden and potential confusion in the CLI reference.

Proposed Solution 2

Create a new command genkit configure appCmd "<run app cmd>" that saves the command to run the app code in a config file in the .genkit directory.

For example, if I first run: genkit configure appCmd "npx tsx --watch src/index.ts"

Then running genkit start afterwards will be the equivalent of running genkit start -- npx tsx --watch src/index.ts.

Pros:

• Will work across language ecosystems in the same exact way.
• New config file is in the .genkit directory, so it won't clutter the project root directory and the details of it are mostly abstracted from the user.

Cons:

• Not very idiomatic to JS ecosystem as it introduces a new config that might very well be a duplicate of the existing dev script in the package.json.

Proposed Solution 3 (Hybrid)

Create a new command genkit configure appCmd "<run app cmd>" that saves the command to run the app code in a config file in the .genkit directory.

1. If config exists, use the config command.
2. If no config exists, fallback to the package.json dev script.

Pros:

• Works across all language ecosystems. We can take a similar approach for Go, for example, where we by default run the main.go file if there is one, but allow configuration of a custom command if that doesn't work.
• Provides explicit configuration when needed, but only when needed.
• Maintains JS idiomatic approach for simple cases (using dev script).
• Solves both Problem 1 (verbose start command) and Problem 2 (cumbersome CLI usage).

Cons:

• Slightly more complex than using only package.json.
• Potential for confusion if config and package.json diverge.
• Still introduces a config file (though only used when needed).

Recommendation

Option 3 for the best balance of often "just working" out of the box while offering a flexible alternative that works across language runtimes.

[anguillanneuf]

I experienced both problems described above, coming from a Python / Java background. I prefer the second proposal because it is easy to follow and also remains flexible.

[chrisraygill]

Update: Just added a hybrid option 3.

@anguillanneuf thanks for the input! What do you think of Option 3?

[pavelgj]

I prefer options 2, for consistency, but I'm open to doing option 1 for cases where we can with 100% certainty determine the runtime. In ambiguous situations (e.g. project uses more than 1 runtime) we make users explicitly configure it.

so option 3a....

function getAppCmd() {
  if (isAppCmdInConfig()) {
    return appCmdFromConfig();
  }
  
  if (hasPackageJson && !hasGoMods && !hasPythonRequirements) {
    return figureOutFromPackageJson();
  }
  if (hasGoMods && !hasPackageJson && !hasPythonRequirements) {
    return 'go run main.go';
  }
  if (hasPythonRequirements && !hasGoMods && !hasPackageJson) {
    return 'python main.py';
  }

  throw 'run: genkit configure appCmd "<run app cmd>"'
}