8000 💫 A big rewrite · Issue #328 · svelte-add/svelte-add · GitHub
[go: up one dir, main page]
Skip to content
This repository was archived by the owner on Oct 20, 2024. It is now read-only.

💫 A big rewrite #328

Closed
BlankParticle opened this issue Dec 27, 2023 · 11 comments
Closed

💫 A big rewrite #328

BlankParticle opened this issue Dec 27, 2023 · 11 comments
Labels
enhancement New feature or request solved-by-rewrite

Comments

@BlankParticle
Copy link
Contributor

As the title suggests, I think svelte-add needs some fundamental changes. It is not broken but also not in a good shape, take #312 or #285 for example, they can be fixed with little bit of logic here and there, but that will not fix the fundamental issue that is lack of project context in adders.

The Proposals

Here are some proposals I have, they are individually debatable and I don't expect everyone to agree on everything

Please move away from submodules

Git submodules aren't the best thing to work with. I have read #12 and understand the gist of it, still I think a monorepo would be the best thing. The last thing anyone want to do is deal with submodules shenanigans.
Also on a personal note, when I looked at the tailwindcss adder it took me way long to realized how it worked with only 3 js files and no package.json or anything. Then I opened __run.js and got more confused by the imports outside of the repo, until I realized I had to look from svelte-add to userstand what was happening.

my suggestion is to archive the other repos and move everything to this central repo. One of the closest match to this kind of setup can be found in https://github.com/catppuccin/userstyles

Better Adder API

Current implementation of adder with __run.js is lacking at many places, what I suggest is to separate out the core utilities in their specific packages like @svelte-add/core or svelte-add-core and ship it as a dependency with svelte-add with the Adders. I promise it will make more sense later.

Now for the adders, instead of exporting bunch of random const from bunch of random files, we can have only one export default defineAdder(), just like how vite does it.
Now to userstand how it helps here is a hypothetical implementation of tailwindcss adder.

import { defineAdder } from "@svelte-add/core";
export default defineAdder({
  name: "TailwindCSS Adder",
  description: "...",
  run: async ({ args, installPackages, createFile, generateConfig, project }) => {
      installPackages(
         { name: "tailwindcss", version: "^3.4", as: "dev" },
         { name: "autoprefixer", /*...*/ },
         /*...*/
        );
      project.prettier.installed && installPackages(/* prettier-plugin for tailwindcss */);
      args.typography && installPackages(/* tailwindcss/typography */);
/* Same with other options */
      createFile(`tailwindcss.config.${project.typescript.installed?"ts":"js"}`,await generateConfig(/*Some Kind of generator with AST manipulation support*/).getCode()); 
 /* Same with PostCSS */
 /* And we are done */
    }
});

We just defined a set of instructions for the adder, now it's the job of core to handle everything. We don't need to handle any cases where there is changes in default svelte config, the user is in a monorepo or any other issues. Also the adder is just defining schema, it will not change anything on files. Then core will look at the schema try to apply it, if anything goes wrong restore original files so that the user is not left with a half broken project.

Checkpoints

Checkpoints is just a fancy term for a test suite for the adder. If we want to check if A adder was run successfully we run this suite which will ensure it.

For tailwindcss the suite may look like this. hasPackage("tailwindcss"), hasPackage(/*Other ones*/), hasConfigFile(/tailwindcss.config.m?(t|j)s/), etc.
Then for a adder like skeleton.dev we can just slap it with a dependsOn("tailwindcss"), it will ensure tailwindcss is installed before adding skeleton.dev other wise prompt the user to install tailwindcss and run it's adder.

Third-party Adders

Third party adders can be boiled down to just a export default defineAdder(), We can show user a warning about the third party adder. Otherwise it should be pretty easy to get schema from any third-party adder and apply it.

Extras

  • May be Typescript 😅, we might need to rewrite whole codebase, why not introduce Typescript. JSDoc are great but it may be difficult for new contributors. Also everyone is already more familiar with Typescript than JSDoc.

I might have some more ideas which I will edit in later. We can discuss and make changes to this proposal as you like.

Thanks ❤️
@manuel3108
Copy link
Member

@BlankParticle Yes, Yes! Yes, Yes! Yes, Yes!

TLDR; I totally agree with you in nearly all the points. As I have dig deeper and deeper in the last weeks / months I had similar thoughts pretty recently.

First of all I want to have a look on some of your points from J's perspective (original author of svelte-add).

Please move away from submodules

J used the separate github repos as a way to promote the different adders via SEO, because no website existed.

Based on the search ranking I, and probably a lot of other users, have experienced, this worked exceptionally well.

Better Adder API

Before the first big rewrite happened, everything was just a few files that were "copy-pasted" inside everyone's project. Unfortunately this caused different adders overriding each others configuration and did not work properly for existing projects.

Based on that, the current state was already a massive improvement.

Now that we have this out of the way, let's get into my personal opinions and thoughts!

Please move away from submodules

Absolutely! In fact I was already preparing a small website, to take over the SEO part. The site is actually present in this repo and deployed, but not linked anywhere because it's not nearly finished. Submodules are a maintenance Burdon and it makes it pretty hard to run the testcases on the adders in the other repos.

Better Adder API

I'm not completely sure about the project/NPM setup yet, but I really like the idea. As of right now, I worked on multiple other adders, but never managed to published them because of weird AST behaviors or my incapability to correctly work with AST's. No matter what, I would like to abstract this as far away as possible as you proposed.

Checkpoints

Based on the things I have done in this repo in the past, I think it would be required that we would have some kind of integration testing of some sort. It happened multiple times, that I changed something and deployed it, and got feedback that in some things did not work in some combinations.

Sure, we cannot catch everything, but we should be able to catch a lot more than we are currently. Currently we only have test in place, to see if the adder got applied correctly and the dependencies could be installed successfully.

Third-party Adders

Exactly.

Extras

Not sure about TS yet, but seeing the current state of this repository pretty much makes this a must. But I have not played with TS too much over the past years, so I would probably need to try it again.

Additional thoughts

  • Possibility to revert adders (Add option to remove svelte adder #289)
  • Automated release management (the current state is crap 🤮 )
  • Keep in mind most of the things should work out of the box for svelte and svelte-kit

Closing thoughts

Yes, you are absolutely right, so thank you so much for mentioning this. In fact in the past I already worked on a rewrite in the past (before being maintainer here), but back then I abandoned the idea.
As this is going to be a completely new rewrite with a bunch of changes, I'm not sure if I would like to keep the name, as it would be something completely different. Currently I have svelte-compose in mind, which is the same workname, my previous attempt had.

@BlankParticle
Copy link
Contributor Author

To be honest I hate the versioning system that is happening in this repo, I think it would be far better to use changesets like svelte's repo.
But no matter what we do 2023.x.x would be the latest version 😅

So I think we might need to create a project, we could name them like svelte-init, svelte-compose, etc.

Also if we are going to do a rewrite we should make a unified Adder api, most project that are made for svelte use their own methods, If the can port the existing adders to this new api, we could convince projects like Skelton, daisyUi to use the unifed Api to avoid wired conflicts. Also If we take control over the core and provide the utilities for building out a schema then handling breaking changes with svelte would be much easier.

So now it's upto you, if you want to create new package or continue with this one.

If we want to create a new package then I have a project structure in mind.

  • core providing the api and utilities
  • cli the package that is executed with pnpx, it should parse args and pass it down to the correct adder, handle input and output to the terminal.
  • templates a meta package that will hold all 1st party adders, shouldn't contain any other dependency than core, should not interact with any files, just return the schema

Any thing you might choose, I would be happy to help out.

@manuel3108
Copy link
Member

Appreciate your feedback and the help offered.

I have already started laying down some groundwork, like repo structure, TS setup, changeset, eslint, prettier and so on in a private repo. Functionality vise there is nearly nothing present at this point. The project is going to be called svelte-compose, at least momentarily.

I will continue working on this in the private for at least a few more days, and invite you to the repo once there is at least something to see functionality wise.

This is the current repo structure:
image

If there is anyone else interested, please let me know here and I will make sure to also invite you!

@BlankParticle
Copy link
Contributor Author

Sure, I would love to help when you get the ground up.
Till then pin this issue

@manuel3108
Copy link
Member

Not going to pin this right now, as I expect this to be a process that will last at least several weeks....

@manuel3108
Copy link
Member

@BlankParticle Actually, I changed my mind.

I have just invited you to the repo.

In the readme you will find a link to vision.md file where I have written down my personal vision, but immensely inspired by what you have shared here.

I would especially be interested in your feedback on the vision.ts file linked somewhere in the vision.md. Easiest way to share your feedback would be to a Issue or PR in that repo.

Thanks so much for your help!

@BlankParticle
Copy link
Contributor Author

Sure, I will look into this tomorrow

@manuel3108
Copy link
Member

Just to give everyone a short update: Everything started coming together pretty recently.

Overall I can say, that the hard work is done by now. Especially the AST manipulation took me many tries to find a syntax that naked sense, is short and powerful.

Apart from that I currently have three composers (tailwindcss, mdsvex, bulma) that are currently working.

I hope that I can get most of the things done within the next month or so to be ready when svelte 5 releases.

There is still lots of things to do (without order):

  • Make the CLI more user friendly by adding some messages mixed with some colors
  • Propose the user to install the packages after applying a composer
  • Add post installation checks (TBD) and tests (POC ready)
  • Add more informations to the website
  • Create composers that are currently missing compared to svelte-add

Uh oh!

There was an error while loading. Please reload this page.
@BlankParticle
Copy link
Contributor Author

Hey sorry, I was the one who proposed the change, but I recently had not chance to work with svelte, so I had not been able to work on this.

@manuel3108
Copy link
Member

No problem at all. Really loved your input though, and many of the things we discussed are still applicable today.

Just wanted to give an update for anyone seeing this issue

@manuel3108 manuel3108 pinned this issue Mar 17, 2024
@manuel3108 manuel3108 added enhancement New feature or request solved-by-rewrite labels Apr 1, 2024
@manuel3108
Copy link
Member

This is supported by svelte-adds successor svelte-compose

@manuel3108 manuel3108 mentioned this issue Apr 14, 2024
Closed
@manuel3108 manuel3108 unpinned this issue May 5, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
enhancement New feature or request solved-by-rewrite
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@manuel3108 @BlankParticle
0