For contributors

Architecture

Project structure

This project is a monorepo with the following structure:

• apps - applications.
  • docs - documentation website.
• demos - demos.
  • all - meta-package for all demos.
  • inline - inline demos for various pages outside of specific framework context.
  • * - demos for each supported framework.
• packages - loader itself, integrations and internal utilities.
  • integration-utils - utility functions and constants for integrations. Bundled with the loader to allow users to write their own integrations.
  • loader - loader’s source code.
  • types - types for usage throughout the project.
  • utils - various utilities for usage throughout the project.
  • *-integration - specific framework integration.
  • vite-astro-entry-generator - a plugin that generates an Astro component that loads a script on the client side.
  • vite-awesome-svg-loader - final loader bundle (in other words, meta-package).
  • vite-file-tree-builder - a plugin that builds a project’s file tree.
• modules.d.ts - types for untyped external modules.

Monorepo management

Turborepo is used to manage monorepo.

Demos

Demos are self-contained NPM packages.

All demos should contain their own scripts and assets. The code and the assets are often duplicated across the demos.

When demo is built, its file tree is formed that will be displayed in the docs website.

Demos should be small and should not have a sprawling file tree.

Demos are built in Vite library mode and rebuilt whenever a change occurs. This pattern avoids necessity for the running multiple web servers.

Scripts

1. generate-sources - generates project’s source code required for building. Runs automatically before any other build command.
2. build - builds whole project.
3. build:packages - builds all packages. Use this while developing to speed up the build.
4. build:apps - builds all apps.
5. build:demos - builds all demos.
6. dev - builds all packages and executes dev all dev commands. This command is resource heavy!
7. dev:docs:standalone - runs dev command for docs packages without running all demos in watch mode. This is a lighter alternative to dev. The docs are still updated whenever demo is rebuilt.
8. lint - lints the code with ESLint.
9. format - formats the code with Prettier.

TypeScript and JavaScript

The primary language for this project is TypeScript. TypeScript should be used while developing loader itself, integrations and demos.

However, build scripts are written in JS to simplify development and speed up the build. Typing is not critical for these scripts. Thus, TypeScript is just not worth it.

Bundlers

Vite is the primary bundler for this project.

Other bundlers may be used, if Vite ecosystem doesn’t have a solution, or specific package requires specific tooling. Examples:

1. vite-awesome-svg-loader meta-package uses tsdown because no other tool was able to correctly build types for multiple entry points.
2. docs app uses Astro and its tooling (it’s Vite internally, but it may change in future).

Custom build scripts and/or plugins may be used in the build process. Ideally, custom additions to the build process should be implemented as bundler’s plugins or build lifecycle hooks. But plain JS scripts are OK, if it makes life easier.

Bundle structure

Every project (package, demo or app) should be bundled into dist directory inside the project’s root.

For example, packages/utils bundle should be in packages/utils/dist directory.

Dependencies

Dependencies that are used by more than one project should be installed for the whole project, i.e. added to the root package.json.

Such dependencies include Vite, TypeScript, Vue, React, Solid, etc.

Local dependencies should be installed in package or app where they’re required.

vite-awesome-svg-loader final bundle dependencies always should be in packages/vite-awesome-svg-loader/package.json file even if they’re duplicated in the root package.json.

Build process

This is how build command works:

1. generate-sources command is ran, and the source code is generated:
   1. vite-awesome-svg-loader source code is generated:
   2. Loader and integrations re-exports are added.
   3. Subpath exports are updated.
   4. Loader and all integrations are added as dependencies.
   5. all-demos package is generated: all demos are added as dependencies.
2. All packages are built.
3. vite-awesome-svg-loader package is built.
4. All demos are built.
5. Apps are built.

Code style

Prettier should be used to format the code. Styles that are left for the user to decide are handled by ESLint rules.

This project tries to keep the source code clean and readable. Please, try to do so as well, i.e. don’t stack ifs too many times, don’t use bit shifts unnecessarily, etc.

Integrations development

Caution

See other frameworks guide before developing

1. Create an issue to notify the community that you’ll be working on your integration.
2. Create an integration package using npx turbo generate workspace command or by copying an existing integration.
3. Develop integration:
   1. Open package.json file inside your integration directory.
   2. Add "integration-utils": "*" dependency.
   3. Develop your integration.
4. Run npm run generate-sources command to regenerate vite-awesome-svg-loader source code. Or just run any build or dev command.
5. Develop demos for your integration:
   1. Duplicate any existing demo and pages in the /apps/docs/src/content/docs directory.
   2. Develop your demos.
   3. Update the docs:
      1. Add a glob import for the demos inside /apps/docs/src/demos directory.
      2. Update the previously copied pages.
      3. Feel free to add your own pages if needed.
6. Submit a PR with your integration.

Loader development

1. Create an issue to notify the community that you’ll be working on your feature.
2. Develop your feature. Make sure to document it with JSDoc.
3. Update the docs to showcase your feature.
4. Test if demos work.
5. Submit a PR.