[RFC] Structure of a Webstone Plugin

[Cahllagerfeld]

Context

Based on problems and issues we have in the current plugin setup we assume changing the structure of them again. There is one main issue we're facing currently: ESM and CJS The CLI requires CJS, while Sveltekit itself requires ESM. This makes it quite painful writing a plugin because we need to support both Module-Architectures

Goal

The main goal is to find a plugin structure that makes it quite straightforward to develop a new plugin in terms of DevX on the one hand and resolves the issues we have with ESM and CJS on the other.

Proposed Solution

Project structure

The suggested folder structure is a mono-repo, having a dedicated project for the CLI-Extensions, and a dedicated Repo for the Sveltekit-Components

.
├── package.json
└── packages
    ├── cli
    │   └── package.json
    └── web
        └── package.json

The structure of the package.jsons in the monorepo would be the following:

- . -> webstone-plugin-rest
- ./packages/cli -> webstone-plugin-cli-rest
- ./packages/web -> webstone-plugin-web-rest

This Monorepo setup would require us the use pnpm for convenient monorepo-management.

Creation Flow of a new plugin

When generating a new plugin we would have a template project that follows the following flow:

1. The monorepo itself with the pnpm setup is a template
2. The project inside the cli-directory is a template repo as well. We would need to think of making the package name dynamic based on the user input. We might want a templating engine here 🤔
3. The command that generates the Sveltekit-Library can be used as it is currently. We would leverage the create-svelte-package for this again.

Use Cases

We're having two potential use cases that occur in plugins:

1. The CLI needs to be extended
2. The CLI doesn't need to extend

These scenarios could be handled by using the private-property in the package.json of the two projects.

Building the packages

We need to decide if we want to use tsc or a bundler in the build process.

• For the web-package we can rely on the build-step from Sveltekit
• The build step for the cli package needs to be run with tsc because we need to ensure a given folder-structure.

Open Questions

• We're having Version Packages #263 open currently. What do we do with these changes? Will we still release the new versions?
• What do we do with PRs that are currently open?
• Do we need another subdirectory inside the CLI-package so we can call ws rest create ..., otherwise the commands will be added at the top level of the CLI?
• Do we still need our own Gluegun-flavor in the future?
• Will we have a default setup for Changeset out-of-the-box?

Next Steps

• Align on the above changes
• Find answers to (most relevant) questions
• Figure out the best possible setup for the monorepo and the sub-projects
• Start automating the creation process of the monorepo

Additional Resources

• https://docs.npmjs.com/cli/v8/configuring-npm/package-json#private
• https://pnpm.io/workspaces

[mikenikles]

Some thoughts on the open questions:

We're having #263 open currently. What do we do with these changes? Will we still release the new versions?

Since these changes are in main already and the release contains a few valuable changes besides the plugins, I suggest we merge the PR and follow up with another release with the changes discussed here. We don't have any users who would be impacted by that.

What do we do with PRs that are currently open?

I would keep PRs related to plugins open and update them once the changes we discuss here are implemented.

Do we need another subdirectory inside the CLI-package so we can call ws rest create ..., otherwise the commands will be added at the top level of the CLI?

Yes, you are right. Nice catch!

Do we still need our own Gluegun-flavor in the future?

That crossed my mind as well. The main change you made to it was to load the CLI from a specific sub directory. Since we move back to a standalone NPM package for the CLI, I think (but please correct me if you disagree) we can drop our fork and use the official gluegun package.

Will we have a default setup for Changeset out-of-the-box?

I like it! Webstone as a project is about best practices and outstanding developer experience, we may as well introduce changesets to plugin authors! Let's do it.

[Cahllagerfeld]

we can drop our fork and use the official gluegun package.

That's my take on it as well 👍

We would need to think of making the package name dynamic based on the user input. We might want a templating engine here

What do you think about this? For the cli-package we would have multiple dynamic parts:

1. The subdirectory inside the cli-project to guarantee that we have a "namespace" for the commands => This can be handled without a templating engine, similar to how it's currently done already
2. The package-name itself in the package.json would need to be set dynamically in the template. => Here we would probably need a dynamic way to replace placeholders

[mikenikles]

1. The subdirectory inside the cli-project to guarantee that we have a "namespace" for the commands => This can be handled without a templating engine, similar to how it's currently done already

You are right, we do need that sub-directory. Luckily, it matches the plugin name (e.g. rest, graphql, payments-stripe, ...) so we can use that as you explained and already implemented.

2. The package-name itself in the package.json would need to be set dynamically in the template. => Here we would probably need a dynamic way to replace placeholders

I wouldn't be too fancy for this. Since package.json is a regular JSON file, I'd just use fs to read it, set the name property, then use fs to write the file.

[Cahllagerfeld]

In the given scenario above we would have a rather big difference between generating a new plugin and generating a new app. (plugin is a monorepo, plugin requires pnpm, etc...). How should we deal with this inside the create-webstone-package to keep everything maintainable?

[mikenikles]

How about we rename packages/create-webstone-app/template to templates and add two sub-directories:

• project
• plugin

Where project contains only a README.md and plugin is what we discuss in this RFC here.

[Cahllagerfeld]

I've created a reference plugin.
Which tools should we preconfigure in our template?

1. Changeset + Changeset-Action
2. Prettier?
3. Eslint?
4. Husky?
5. Turborepo??

[mikenikles]

As discussed:

1. ✅ Changeset + Changeset-Action
2. ✅ Prettier
3. ❌ Eslint
4. ❌ Husky
5. ❌ Turborepo