DO NOT MERGE: POC for new create flow

[mmason2-godaddy]

Summary

This exercise was highly valuable as it uncovered the significant complexity surrounding the create flow. Several overarching areas of complexity emerged:

• Logic location
• Variations in the final application structure

Running the POC

cd ./gasket/create-gasket-app
npm i -g .
create-gasket-app cool-app --preset-path /<local-path>/gasket-preset-next

You can proceed through the prompts quickly, as defaults have been pre-configured. The final application will use the App Router with TypeScript and an HTTPS proxy.

Goals

Before starting the POC, I brainstormed a few objectives to define what a meaningful change to the create flow would entail and what factors would justify such a significant change:

• Speed up the creation of new applications
• Simplify the application creation process
• Improve maintainability of the tool, plugins, and presets
• Centralize prompts and application shape logic
• Reduce preset dependencies (i.e., plugins should not be dependencies of a preset)

After exploring a redesigned create flow, several key insights emerged:

• There is no definitive "best" solution for structuring the create flow.
• The two primary options are abstraction/semantic organization (the current approach) or monolithic presets.

Generator Files

I iterated through multiple potential file structures for the generator directory:

• Preset by application type (app-router, page-router, custom-server, API)
• Preset by application type with TypeScript variations (app-router, page-router, custom-server, API, plus their TypeScript equivalents)
• Preset by category (e.g., Next.js, API) with all variations consolidated into the generator directory

The final choice was Preset by category, with TypeScript variations included in the generator directory:

/generator/app-router/js
/generator/app-router/ts

POC Details

The POC introduced an inversion of responsibilities between the presets and the CLI. The preset now handles most responsibilities, while the CLI simply loads the preset and defines the initial CreateContext.

Key changes and concepts introduced:

• CreateContext proved to be a valuable model and was consistently used.
• ConfigBuilder remains relevant and widely used.
• Presets now export a function executed by the CLI upon loading - example.
• The CLI creates the destination application directory.
• All prompts are executed sequentially, with mutations happening after all results are available - example.
• Introduced the concept of "actions" (create hooks) - example.
• The documentation plugins (docs, Docusaurus, metadata) serve as an example of CreateContext's broad applicability and an example of multiple context scopes in one logical handler - example.
• The appType logic in action handlers determines the files added to the FileSet - example.
• Introduced a utility to handle file placement - example, including basic glob functionality - example.
• Established a _variation directory within the generator files - example.
• Refined package generation: changes from action handlers are merged with a base package configuration - example.
• The gasket configuration file is now generated based on the final package file rather than being derived from the CLI - example.
• Plugins for the gasket file are derived from the final package file - example.
• Introduced a dependency ledger to track package dependencies - example ledger.

Issues Identified

Package File Generation

Programmatically generating the package file remains the most reliable approach. However, maintaining accuracy while deviating from current patterns is challenging. The merging of multiple ConfigBuilder package instances works but introduces complexity and potential errors.

Dependency Awareness

Maintaining a dependency ledger for plugin dependencies is not ideal. While the ledger built during prepublish is functional, it adds an additional layer of domain knowledge that must be accounted for.

Templating

Originally, I considered replacing Handlebars templating with a search-and-replace approach in action handlers. However, this proved impractical due to excessive variation. Certain templates rely on CreateContext values that do not directly correlate, making abstraction infeasible.

Organization

While the current separation of concerns presents challenges (e.g., required domain knowledge, multiple mutation sources, mutation timing issues), a monolithic approach is unlikely to resolve them outright. Instead, it would introduce different organizational complexities. The POC model offers greater control over grouping, timing, and context, but it may not offset the risks associated with encapsulating all logic within presets.

Post-POC Path

Given the scope and scale of these changes, a gradual, incremental approach is the best path forward. As a team, we need to align on our core objectives. Based on the goals outlined earlier, we can make meaningful improvements with minimal risk.

Recommended next steps:

• Reevaluate the postCreate process and consider removing it.
• By eliminating postCreate, we can avoid installing modules automatically, thereby speeding up the application creation process.
• Investigate an approach where prompts are gathered before making mutations, this can relieve pain points in shared context and ordering.

Conclusion

This POC was a valuable exercise in assessing the feasibility of modifying the create process. It helped gauge the scope and complexity of such changes, revealing both opportunities and challenges. The insights gained from this work suggest that instead of making sweeping changes, a strategy of small, incremental improvements will be the most effective approach moving forward. By focusing on targeted enhancements, we can optimize the creation process while minimizing risk and disruption.

[changeset-bot]

⚠️ No Changeset found

Latest commit: d2c173a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR