svelte-compose / svelte-compose

⚠️ MOVED: https://github.com/svelte-add/svelte-add/ ⚠️ Add different tools to your new or existing svelte / svelte-kit project

svelte-compose

⚠️ Moved to svelte-add

svelte-compose is a tool to add many different tools to your svelte/kit project.

This is a monorepo, containing the following packages:

Package	Description
@svelte-compose/ast-manipulation	Provides tools for manipulating JS, CSS and HTML AST's
@svelte-compose/ast-tooling	Bundles different tools for parsing and serializing JS, CSS and HTML AST's
@svelte-compose/cli	Allows you to apply different composers at once and guides you interactively through the composer initialization
@svelte-compose/composers	That's the place where all official composers live
@svelte-compose/core	Provides all utilities for easy application of composers
@svelte-compose/dev-utils	Used to do some maintenance tasks inside the repository
@svelte-compose/testing-library	Provides tools to test a composers with all it's option in different project templates
@svelte-compose/tests	Uses testing-library to execute the tests for all official composers
@svelte-compose/website	The website of this project

Contributing

Please see the contribution guidelines

Licensing

MIT

Thanks to

• J who initially created svelte-add
• All contributors of svelte-add
• BlankParticle who initially brought up the idea of a full rewrite

svelte-compose's Issues

Add pre / post-installation checks

Topic

core, tests

Description

Currently it is possible to apply the same composer multiple times to a project. Additionally, we don't have a way to detect if a composer is supported on the current computer (external dependencies installed, see tauri which requires rust)

Describe the solution you'd like

I have previously already added some types to get a feeling for all components of a composer. The types are not accurate and do not provide any meaningful enhancements. Everything needs to be re-thinked.

Preconditions

Preconditions need to ensure that a given composer can be used within the given environment. This is especially useful, when considering composers that require some other globally installed tooling to work correctly (#9). Preconditions are workspace independent and can only check for the global environment.

Here is a sample pre installation check to determine if the Tauri adder could be installed:

export const checks = defineComposerChecks({
    options,
    preconditions: [
        {
            name: "rust installed",
            run: ({ execute }) => {
                // execute a shell command and gather it's output and exit code
                const { output, exitCode } = execute("cargo", ["version"]);

                // if the exit code is 0, we can assume that cargo / rust is installed correctly
                return exitCode == 0;
            },
        },
    ],
    preInstallation: [],
    postInstallation: [],
});

Precondition checks should be executed before the composer runs to avoid unnecessary file modifications in case any of the preconditions fails. In case at least one precondition fails, the composers should not install itself and rather fail. The user should be notified with an appropriate error message.

Pre installation checks

Pre installation checks are executed before the adder executes, but after the project has been detected / created and therefore have full access to the workspace (minus the options, as they have not been chosen yet). These checks should identify if

• the composer is supported in the current environment (svelte / kit)
• the composer has already been applied or the tool to compose is already setup (i.e. the tailwdincss.config.js file is already present / installed packages already present)

Post installation checks

Should check if a composer was successfully installed, basically they are the same as the pre installation checks, but they are executed after a composer was executed to determine if everything was set up as expected.

Further thoughts

Those ideas are mainly taken from svelte-add (predecessor of svelte-compose) and need to be partially re-thought.

Do we really need the post installation checks?
Is there any reason we would not trust in our code? Additionally we have tests that run when merging PR's that ensure that alle test execute correctly. Those tests not only check that that special files are present and contain special contents, but run explicit integration tests for each possible composer and svelte template possibility.

Do we really need pre installation checks?
Once we got this far, let's think if we need pre installation checks. Should they be optional? For most composers it should be enough to check if any of the dependencies is already present. But what if we have something like #18 (Github pages) that does not apply a dependency? Should we provide pre build checks for checking the dependencies? How should the method definition of those look like?

semantic-release with support for Github/npm

Website

https://semantic-release.gitbook.io/semantic-release

Documentation

https://semantic-release.gitbook.io/semantic-release

Integration summary

1. Install the following dependencies: semantic-releae, @semantic-release/commit-analyzer, @semantic-release/npm, @semantic-release/github, husky and lint-staged (see notes below)
2. modify package.json and the following section:

        "release": {
                "plugins": [
                        "@semantic-release/commit-analyzer",
                        "@semantic-release/release-notes-generator",
                        "@semantic-release/github"
                ],
                "branches": [
                        "main",
                        "next"
                ]
        },
        "lint-staged": {
                "**/*.{js,jsx,ts,tsx,html,css,json}": [
                        "pnpm run format"
                ]
        }
}

5. Also add the following scripts to package.json:

                "lint": "prettier --check . && eslint .", 
                "lint-staged": "lint-staged",
                "format": "prettier --write .",
                // setup husky
                "prepare": "husky",
                // ensure everyone has commit hooks set up
                "postinstall": "pnpm run prepare",
                // actual semantic-release script 
                "release": "semantic-release"

6. Add the following to `.husky/pre-commit'

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# dlx downloads "lint-staged" every time, resulting in long commit delays
# when internet connection is slow
# Solution: Install as dev dependency and run as target from package.json instead
pnpm run lint-staged

7. Add the following to Github actions (further configuration for repository permissions is required)

      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Publishing to NPM is not necessary for websites
          # NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: pnpm run release

Further details

Explanation

This request is augmenting the Github pages composer.

As a note ahead, the formatting and linting might be a seperate composer. It is just how I did it.

Setting up a Continuous Integration, Delivery and Deployment pipeline can take several hours per repository.

Using Conventional Commits and semantic-release can help to fully automated the process, including

• automated semantic versioning
• tagging in Git
• publishing a release to npm or Github pages
• Release notes on Github

The composer should take over additional tasks to ensure a consistent and productive development experience:

• check format of commit messages using husky
• Lint and fix any changed files using lint-staged for consistent formatting using prettier (shipped with sveltekit)

Options

Ask for

• github and npm plug-ins of semantic-releae
• ask for lint-staged, and husky

Configure Github Actions

The Github Actions are already configured to build and deploy the project to Github Pages.

Therefor you need to set two permissions in the settings of your repository:

• In your browser, open the repository settings
• Go to the Actions section
• In the Workflow permissions, select Read and write permissions
• Check Allow GitHub Actions to create and approve pull requests

Add possibility to install / update dependencies

Topic

testing-library

Description

Currently the user needs to rember himself to install / update the dependencies after applying a composer.

Describe the solution you'd like

Instead, we should ask the user if he want's to install the dependencies. We should provide him with a selection of packages managers we found on the users system. Additionally, the most relevant package manager should be pre-selected.

We should at least consider the following package managers:

• npm
• pnpm
• yarn
• bun see svelte-add/svelte-add#333
• deno (Not in the focus at this point)

Visual Studio Code configuration

I think it would be great if there would be a composer for adding Svelte
-specific Visual Studio code configuration, so it is less of a hassle.

.vscode/launch.json

{
        "version": "0.2.0",
        "configurations": [
                {
                        "name": "Launch server",
                        "request": "launch",
                        "runtimeArgs": ["run-script", "dev"],
                        "runtimeExecutable": "pnpm",
                        "skipFiles": ["<node_internals>/**"],
                        "type": "node",
                        "console": "integratedTerminal"
                },

                {
                        "type": "firefox",
                        "request": "launch",
                        "name": "Launch Firefox",
                        "reAttach": true,
                        "url": "http://127.0.0.1:5173",
                        "webRoot": "${workspaceFolder}"
                }
        ],
        "compounds": [
                {
                        "name": "Both",
                        "configurations": ["Launch server", "Launch Firefox"]
                }
        ]
}

.vscode/extensions.json

Note: This is a matter of personal taste and some of these could also be part of the other composers for Tailwind or Github Actions.

{
        "recommendations": [
// Tailwind support
                "bradlc.vscode-tailwindcss",
               // helps creating 🎸 commit messages in Conventional Commits format 
"vivaxy.vscode-conventional-commits",
               // Run Firefox with debugger attached "firefox-devtools.vscode-firefox-debug",
// Github actions Integration 
                "github.vscode-github-actions",
                "svelte.svelte-vscode",
// Load .nvmrc and setup nvm for launch configurations and terminals
                "henrynguyen5-vsc.vsc-nvm",
// most opionated
                // "k--kato.intellij-idea-keybindings",
                "1yib.svelte-bundle",
// Show documentation for Tailwind classes in-editor
                "austenc.tailwind-docs"
        ]
}

Also look for extensions with MDSveX support.

.vscode/settings.json

Set package manager

{
        "npm.packageManager": "pnpm"
}

Add Threlte studio

Topic

threlte

Description

Was just showcased in the summit.

Describe the solution you'd like

No response

Threlte

Website

https://threlte.xyz/

Documentation

https://threlte.xyz/docs/learn/getting-started/installation

Integration summary

1. install dependencies as per the documentation. Maybe ask the user what he plans on doing to install only the required dependencies
2. modify vite.config.js and mark threlte as noExternal
3. if using typescript, adapt tsconfig.json

Maybe ask if we should include a small demo, maybe one from here: https://threlte.xyz/docs/learn/getting-started/your-first-scene

Further details

No response

Tauri

Website

https://tauri.app/

Documentation

https://tauri.app/v1/guides/getting-started/setup/sveltekit

Integration summary

1. Make sure all prerequisites are met: https://tauri.app/v1/guides/getting-started/prerequisites/ (depends on #7)
2. use adapter static
3. enable prerendering (modify +layout.js
4. Create the rust project npm run tauri init

Further details

This composer would only support kit.

Is there a way we can test this composer automatically? Currently I don't see a way as it requires so many and different prerequisites, that differ from os

Github Pages

Website

https://pages.github.com/

Documentation

https://docs.github.com/en/pages

Integration summary

1. create new workflow file inside .github/workflows/
2. install dependencies, build website
3. Use external action for publishing i.e. : https://github.com/svelte-compose/svelte-compose/blob/main/.github/workflows/changesets.yml#L56-L62
4. Ask for adding cname (if not check that svelte.config.js is properly setup for a subdirectory deployment)

Further details

It's always a pain to create these config files. The resulting yml file is going to be opinionated in some parts, but the good think is that you can modify it later on without any problems.

Storybook

Website

https://storybook.js.org/

Documentation

Kit: https://storybook.js.org/docs/get-started/sveltekit Svelte: https://storybook.js.org/docs/get-started/svelte-vite
Svelte-Addon: https://storybook.js.org/addons/@storybook/addon-svelte-csf

Integration summary

1. apparently only npx storybook@latest init

Further details

If it's really as simple as shown above, do we really need a composer for this?