{"id":28207608,"url":"https://github.com/kouts/vite-treeshakable-library","last_synced_at":"2026-03-01T09:03:28.843Z","repository":{"id":270754340,"uuid":"901949935","full_name":"kouts/vite-treeshakable-library","owner":"kouts","description":"A Vite template to create a treeshakable library","archived":false,"fork":false,"pushed_at":"2025-12-31T16:27:48.000Z","size":442,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-02T19:29:22.538Z","etag":null,"topics":["javascript-library","library","starter-template","template","tree-shaking","typescript","typescript-library","vite","vitest","vue"],"latest_commit_sha":null,"homepage":"https://kouts.github.io/vite-treeshakable-library/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kouts.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-11T16:06:31.000Z","updated_at":"2025-12-31T16:27:51.000Z","dependencies_parsed_at":"2025-01-02T21:34:15.083Z","dependency_job_id":"0bc95c09-fe34-4352-90dc-8572a879be82","html_url":"https://github.com/kouts/vite-treeshakable-library","commit_stats":null,"previous_names":["kouts/vite-treeshakable-library"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/kouts/vite-treeshakable-library","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kouts%2Fvite-treeshakable-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kouts%2Fvite-treeshakable-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kouts%2Fvite-treeshakable-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kouts%2Fvite-treeshakable-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kouts","download_url":"https://codeload.github.com/kouts/vite-treeshakable-library/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kouts%2Fvite-treeshakable-library/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29965419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T06:55:38.174Z","status":"ssl_error","status_checked_at":"2026-03-01T06:53:04.810Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript-library","library","starter-template","template","tree-shaking","typescript","typescript-library","vite","vitest","vue"],"created_at":"2025-05-17T12:16:14.966Z","updated_at":"2026-03-01T09:03:28.834Z","avatar_url":"https://github.com/kouts.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vite-treeshakable-library \u003ca href=\"https://npm.im/@kouts/vite-treeshakable-library\"\u003e\u003cimg src=\"https://badgen.net/npm/v/@kouts/vite-treeshakable-library\"\u003e\u003c/a\u003e ![](coverage/badge.svg)\n\nThis repository provides a [Vite](https://vite.dev/) template for creating JavaScript libraries optimized for tree-shaking. While it is pre-configured to support [Vue 3](https://vuejs.org/) and [Tailwind CSS](https://tailwindcss.com/), it is flexible enough to be adapted for React, vanilla JavaScript, or other frameworks. The goal of this template is to simplify the process of building, documenting, testing, and publishing modern libraries to [npm](https://www.npmjs.com/).\n\n## Features\n\n- **Vite-Powered Development:**\n  - Fast development and optimized builds.\n  - Pre-configured for tree-shaking to reduce bundle sizes.\n- **TypeScript Support:**\n  - TypeScript setup for type safety and better developer experience.\n  - Emits TypeScript declaration files for strong type support.  \n- **Component Library Support:**\n  - Out-of-the-box support for Vue 3 components and utilities.\n  - Includes example components such as `VAlert`.\n- **Tailwind CSS Integration:**\n  - Includes Tailwind theme and custom styles for shared design tokens and utility classes.\n- **Storybook Integration:**\n  - Documentation and components preview via [Storybook](https://storybook.js.org/).\n  - Storybook deployment to GitHub Pages.\n  - Visual regression testing with Playwright for Storybook stories.\n- **Playground Environment:**\n  - A playground setup for testing and previewing your components in isolation.\n- **Path Aliases:**\n  - Simplify imports with path aliases for library development.\n- **Testing:**\n  - Unit testing with [Vitest](https://vitest.dev/).\n  - Starting with 100% test coverage.\n- **Code Quality:**\n  - Pre-configured [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/).\n  - [Lint-staged](https://github.com/lint-staged/lint-staged) and [Husky](https://typicode.github.io/husky/) for pre-commit hooks.\n- **Automated Releases:**\n  - [Semantic-release](https://github.com/semantic-release/semantic-release) and GitHub Actions to automate versioning and `npm` publishing.\n\n---\n\n## Getting Started\n\n### Clone the Repository\n\nClone the repository using `degit`:\n\n```bash\nnpx degit @kouts/vite-treeshakable-library my-library\n```\n\n### Rename the Library\n\nThe template uses the name `vite-treeshakable-library` in various files and also `Vite treeshakable library` as the title. Replace this with your desired library name:\n\n1. Update `name` and other relevant fields in `package.json`.\n2. Replace occurrences of `vite-treeshakable-library` in:\n   - `README.md`\n   - `vite.config.ts`\n   - Any other relevant files.\n\nThis ensures your library is correctly identified during builds and deployment.\n\n### Install Dependencies\n\n```bash\npnpm install\n```\n\n### Playground\n\nThe template includes a **playground** for testing and previewing your components in an isolated environment. To launch the playground:\n\n```bash\npnpm run dev\n```\n\nThe playground can be found in the `playground` directory. Add pages or components there to test them independently before integrating them into the library.\n\n### Building the Library\n\nTo build the library for production and check the output files in the `dist` directory:\n\n```bash\npnpm run build\n```\n\n### Storybook\n\nRun Storybook for interactive component development:\n\n```bash\npnpm run storybook\n```\n\nVisit the Storybook UI at `http://localhost:6006`.\n\nTo deploy Storybook to GitHub Pages, this template includes a pre-configured GitHub Actions workflow. Simply push your changes to the `main` branch, and the workflow will:\n\n1. Build the Storybook static files.\n2. Deploy the `storybook-static` directory to GitHub Pages automatically.\n\nNo manual steps are needed to deploy Storybook.\n\n### Adding Components\n\nIt is recommended to co-locate components with their tests and stories for better organization. Components are located in the `lib/components` directory.  \nTo add a new component:\n\n1. Create a new component file e.g. `lib/components/{component-name}/{component-name}.vue`\n2. Add unit tests in the corresponding `lib/components/{component-name}/{component-name}.spec.ts` file.\n3. Create Storybook stories for the component under `lib/components/{component-name}/{component-name}.stories.ts`.\n4. Export your component in `lib/components/index.ts`.\n\n### Vite Configuration / Tree-Shaking\n\nIn `vite.config.ts`, the `build.lib.entry` option defines the entry points for the library. The `createEntries` function dynamically generates an entry point for each file in the `lib/` directory (such as `.ts` and `.vue` files), allowing Rollup to split them into separate chunks. This approach ensures effective tree-shaking by including *only* the used code in the final bundle. It also excludes unnecessary files, such as tests or Storybook stories, avoiding the creation of redundant chunks and optimizing the output. This method offers greater flexibility and control over the chunking process compared to using `output.preserveModules`. For more details, see the [Rollup documentation](https://rollupjs.org/configuration-options/#input).\n\n### Tailwind Theme and Styles\n\nThis library uses [Tailwind CSS v4](https://tailwindcss.com/), which introduces a CSS-first configuration approach using the `@theme` directive.\n\nThe library's design tokens (colors, fonts, etc.) are defined in `lib/assets/lib.css` using the `@theme` directive. This file can also include any custom utility classes or component styles:\n\n```css\n@theme {\n  --color-midnight: #1e293b;\n  --color-ocean: #0ea5e9;\n  /* ... more tokens */\n}\n```\n\nThis CSS file is automatically bundled and exported as `@kouts/vite-treeshakable-library/assets/lib.css`. Consumer projects import this CSS to access the library's theme tokens, custom utility classes, and component styles.\n\nTo use the library's Tailwind theme and styles in a consumer project:\n\n1. Install Tailwind CSS v4 and its Vite plugin:\n```bash\npnpm i -D tailwindcss @tailwindcss/vite\n```\n\n2. Add the Tailwind plugin to your `vite.config.ts`:\n```ts\nimport tailwindcss from '@tailwindcss/vite'\n\nexport default defineConfig({\n  plugins: [tailwindcss()],\n})\n```\n\n3. Import the library's styles in your project's main CSS file:\n```css\n@import 'tailwindcss';\n@import '@kouts/vite-treeshakable-library/assets/lib.css';\n```\n\nThis gives your project access to the library's theme tokens (e.g., `bg-midnight`, `text-ocean`), custom utility classes, and component styles.\n\n---\n\n## Using Path Aliases\n\nThis template supports path aliases for cleaner imports. When building the project, path aliases will get replaced with relative paths (using [resolve-tspaths](https://github.com/benyap/resolve-tspaths)) so that the resulting code can be consumed correctly without any errors.  \nThe aliases are configured in the following files:\n\n- **`vite.config.ts`:**\n  ```ts\n  resolve: {\n    alias: {\n      '@': resolve(__dirname, 'playground'),\n      '@lib': resolve(__dirname, 'lib'),\n      '@assets': resolve(__dirname, 'playground/assets'),\n    },\n  },\n  ```\n\n- **`tsconfig.json` and `tsconfig.lib.json`:**\n  ```json\n  {\n    \"compilerOptions\": {\n      \"paths\": {\n        \"@/*\": [\"playground/*\"],\n        \"@lib/*\": [\"lib/*\"],\n        \"@assets/*\": [\"playground/assets/*\"]\n      }\n    }\n  }\n  ```\n\nUse these aliases in your code to simplify imports, e.g., `import { VAlert } from '@lib/components'`.\n\n---\n\n## TypeScript Declaration Files\n\nThe build process emits TypeScript declaration files to ensure strong type support. These files are generated into the `dist` directory during the build step. Ensure your components and utilities are properly typed for better developer experience.\n\nTo build and emit the TypeScript declaration files, run:\n\n```bash\npnpm run build\n```\n\nVerify the `dist/lib/index.d.ts` file for the declarations.\n\n---\n\n## Using the Template for other Frameworks\n\nTo adapt this template for frameworks like React or vanilla JavaScript:\n\n1. Replace Vue-specific dependencies with those for your framework.\n2. Update `vite.config.ts` and other configuration files as needed.\n3. Modify the example components and utilities to match your framework.\n\n---\n\n## Publishing Your Library\n\nThis repository uses **semantic-release** for automated `npm` publishing with [Trusted Publishers](https://docs.npmjs.com/trusted-publishers) (OIDC authentication). This eliminates the need for long-lived npm tokens, providing enhanced security through short-lived, workflow-specific credentials.\n\n### Setting Up Trusted Publishing\n\n1. Navigate to your package settings on [npmjs.com](https://www.npmjs.com/) and find the \"Trusted Publisher\" section.\n2. Select \"GitHub Actions\" as your provider.\n3. Configure the following fields:\n   - **Organization or user**: Your GitHub username or organization name\n   - **Repository**: Your repository name\n   - **Workflow filename**: `release.yml` (or your release workflow filename)\n   - **Environment name** (optional): If using GitHub environments for deployment protection\n\nFor more details, refer to the [npm Trusted Publishers documentation](https://docs.npmjs.com/trusted-publishers).\n\n### Release Process\n\nFollow these steps for a seamless release:\n\n1. Ensure all changes are committed using **conventional commit messages**:\n   - Example commit message: `feat: add new button component`\n   - For guidance, refer to the [Conventional Commits](https://www.conventionalcommits.org/) specification.\n\n2. Push your changes to the `main` branch. The GitHub Actions workflow will:\n   - Run tests and validate your code.\n   - Determine the next version based on your commit messages.\n   - Publish the package to npm automatically using OIDC authentication.\n   - Generate provenance attestations for your package.\n   - Update the changelog and create a GitHub release.\n\n3. Monitor the Actions tab in your repository to ensure the release completes successfully.\n\n**Note:** Ensure your GitHub Actions workflow includes the `id-token: write` permission, which is required for OIDC token generation. Refer to the [semantic-release documentation](https://semantic-release.gitbook.io/semantic-release/) for more information.\n\n---\n\n## Contributing\n\nContributions are welcome! Please ensure that your code adheres to the following:\n\n- **Conventional Commits:** Use conventional commit messages for versioning and changelog generation.\n- **Testing:** Add tests for all new components and features.\n- **Code Style:** Run `pnpm run lint-fix` before committing.\n\n---\n\n## Feedback\n\nIf you find this template useful or have suggestions for improvement, feel free to open an issue or submit a pull request.\n\n\n---\n\n\u003e Use the following boilerplate for the README.md file of your library.\n\n# README boilerplate\n\nThe [Vite treeshakable library](https://github.com/kouts/vite-treeshakable-library) is a comprehensive suite of feature-rich UI components and utilities.\n\nThe library is built using [Vue 3](https://vuejs.org/) and [Tailwind CSS](https://tailwindcss.com/) and is designed to be used in Vue 3 projects.\n[Vite](https://vitejs.dev/) is used as the build tool for the library and [Storybook](https://storybook.js.org/) is used for component development and documentation.\n\n## Installation and Usage\n\nInstall the package and its dependencies using `pnpm`:\n\n```bash\npnpm i vue @kouts/vite-treeshakable-library\n```\n\nInstall Tailwind CSS v4 and its Vite plugin:\n\n```bash\npnpm i -D tailwindcss @tailwindcss/vite\n```\n\nAdd the Tailwind plugin to your `vite.config.ts`:\n\n```ts\nimport tailwindcss from '@tailwindcss/vite'\n\nexport default defineConfig({\n  plugins: [tailwindcss()],\n})\n```\n\nImport Tailwind and the library's styles in your project's `main.css` file:\n\n```css\n@import 'tailwindcss';\n@import '@kouts/vite-treeshakable-library/assets/lib.css';\n```\n\nImport and use the components you need in your Vue 3 project:\n\n```html\n\u003ctemplate\u003e\n  \u003cVAlert type=\"success\"\u003eThis is a success alert\u003c/VAlert\u003e\n\u003c/template\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\n  import { VAlert } from '@kouts/vite-treeshakable-library';\n\u003c/script\u003e\n```\n\nIf you are using Jest for unit testing in your consumer project, you will need to add the following to your Jest configuration:\n\n```js\n{\n  moduleNameMapper: {\n    '^@kouts/vite-treeshakable-library$': '\u003crootDir\u003e/node_modules/@kouts/vite-treeshakable-library/dist/cjs',\n  }\n}\n```\n\n## Contributing\n\n:fire: **HEADS UP!** This repo uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) and [semantic-release](https://github.com/semantic-release/semantic-release) to automate the whole package release workflow including: determining the next version number, generating the release notes, and publishing the package to npm.  \nCommit messages have to follow the commit message format when contributing.\n\n---\n\nWhen adding a new component to the library, please make sure to add unit tests and Storybook stories for it.  \nWe strive to maintain a high level of code quality and test coverage in this project.\n\n## Project setup for development\n\nThis project uses [pnpm](https://pnpm.io/) as the package manager.\n\n### Install dependencies\n\n```bash\npnpm install\n```\n\n### Start the dev server\n\n```bash\npnpm run dev\n```\n\n### Run Storybook\n\n```bash\npnpm run storybook\n```\n\n### Run Storybook tests\n\n```bash\npnpm run test-storybook\n```\n\n## Run unit tests\n\n```bash\npnpm run test:unit\n```\n\n## Run unit tests and generate coverage report\n\n```bash\npnpm run test:unit-coverage\n```\n\n### Lint files\n\n```bash\npnpm run lint\n```\n\n### Lint and fix files\n\n```bash\npnpm run lint-fix\n```\n\n### Run Typechecks\n\n```bash\npnpm run typecheck\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkouts%2Fvite-treeshakable-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkouts%2Fvite-treeshakable-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkouts%2Fvite-treeshakable-library/lists"}