# Lit Starter Kit Welcome to the Lit Starter Kit. This is not an official kit for the Lit library, but this is a tool to get a component library up and running quickly. ## Prerequisites Before getting started, make sure you have the following installed: - **Node.js** (v18 or higher recommended) ## Features This repository is designed to be a "batteries included" repo, so you can hit the ground running with what you need to start delivering components. This repo includes: - ✅ Library and component scaffolding - ✅ [Storybook](https://storybook.js.org/docs/get-started/frameworks/web-components-vite?renderer=web-components) integration (with [helpers](https://www.npmjs.com/package/wc-storybook-helpers)) - ✅ CDN build (in `/cdn`) - ✅ NPM build (in `/dist`) - ✅ Testing - ✅ Documentation - ✅ [React wrappers](https://wc-toolkit.com/integrations/react/) (in - `/react`) - ✅ [JSX integration](https://wc-toolkit.com/integrations/jsx/) - (in `/types`) - ✅ [Vue.js integration](https://www.npmjs.-com/package/-custom-element-vuejs-integration) (in `/types`) - ✅ [Svelte integration](https://www.npmjs.-com/package/-custom-element-svelte-integration) (in `/types`) - ✅ [Linter](https://wc-toolkit.com/integrations/wctools/) (in `/wc.config.js`) ## Getting Started You can choose to fork this repository directly or you can run the following command to create a new project. ```bash npm init lit-starter-kit your-project-name ``` Once created, navigate to your project directory and install dependencies: ```bash cd your-project-name ``` ## Project Structure Understanding the project structure will help you navigate and customize the library: ```text ├── src/ # Source code for your components │ ├── index.ts # Main entry point │ └── components/ # Component definitions ├── dist/ # NPM package build output (generated) ├── cdn/ # CDN build output (generated) ├── react/ # React wrapper components (generated) ├── types/ # Framework type definitions (JSX, Vue, Svelte) ├── plop-templates/ # Component generator templates ├── public/ # Build outputs for CDN, HTML, and React └── .storybook/ # Storybook configuration ``` ## Running the Code The development environment uses [Storybook](https://storybook.js.org/) to showcase and document the components. The documentation files are written in MDX files to increase portability in case you wan to use a different tool for documenting your components. ```bash npm run dev ``` This command will: - Build your components - Watch for changes and rebuild automatically - Start Storybook on http://localhost:6006 ### Creating a New Component This project leverages [plop](https://www.npmjs.com/package/plop) to generate new components in your library. You can create a new component by running the following command and following the prompts. ```bash npm run new ``` This will scaffold: - Component TypeScript file - Styles file - Test file - Storybook stories - MDX documentation ## Linting & Formatting Maintain code quality with built-in linting and formatting tools: ```bash # Run all linters npm run lint # Run ESLint npm run lint:eslint # Run Prettier check npm run lint:prettier # Auto-fix issues npm run format ``` ## Building the Project Generating the final build assets will generate the `dist` assets for the NPM package, the content for the CDN located in the `cdn` directory at the root of the project, as well as the meta content for your components like framework integrations like types and react wrappers. ```bash npm run build ``` This generates: - **`/dist`** - NPM package distribution files - **`/cdn`** - CDN-ready bundles for direct browser usage - **`/react`** - React wrapper components - **`/types`** - TypeScript definitions and framework integrations - **`custom-elements.json`** - Component metadata manifest ### Building for Specific Targets ```bash # Build only CDN version npm run build:cdn # Build only React wrappers npm run build:react # Build static Storybook documentation npm run build-storybook ``` ## Testing the Components Tests are written and executed using [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) which execute your tests in _real_ browsers to validate your APIs are working as expected in the environments you intend to be using them in. Tests can be configured in the `web-test-runner.config.js` file located at the root of the project. Tests can be run using the following command: ```bash npm test ``` ## Using Your Components Once built, your components can be used in multiple ways: ### Via NPM Package ```bash npm install your-package-name ``` ```javascript // Import all components import 'your-package-name'; // Or import specific components import 'your-package-name/components/button'; // Use in your HTML Click Me ``` ### Via CDN ```html Click Me ``` ### With React ```jsx import { MyButton } from 'your-package-name/react'; function App() { return Click Me; } ``` ### With TypeScript/JSX TypeScript and JSX support is included via the `/types` directory. Type definitions are automatically recognized by TypeScript when you import the components. ### With Vue.js and Svelte Framework-specific type integrations are provided in the `/types` directory for Vue.js and Svelte to ensure proper type checking and intellisense. ## Publishing Your Library Before publishing, update your package details: 1. **Update package.json:** ```json { "name": "@your-scope/your-package-name", "version": "1.0.0", "description": "Your component library description", "author": "Your Name", "repository": { "type": "git", "url": "https://github.com/your-username/your-repo" } } ``` 2. **Build and publish:** ```bash npm run build npm publish ``` Or use the deploy script: ```bash npm run deploy ``` 3. **For scoped packages:** ```bash npm publish --access public ``` ## Customization ### Renaming Your Package 1. Update the `name` field in [package.json](package.json) 2. Update component prefixes in your source files 3. Update import paths throughout the project ### Configuring the Build - **Vite config:** [vite.config.ts](vite.config.ts) - **TypeScript:** [tsconfig.json](tsconfig.json) - **Custom Elements Manifest:** [custom-elements-manifest.config.js](custom-elements-manifest.config.js) ### Theming & Styling Components use Lit's styling system. Create shared styles in a common file and import them into your components: ```typescript import { css } from 'lit'; export const sharedStyles = css` :host { /* Your shared styles */ } `; ``` ## Deploying Documentation To deploy your Storybook documentation: ```bash npm run build-storybook ``` This creates a static site in `storybook-static/` that can be deployed to: - GitHub Pages - Netlify - Vercel - Any static hosting service ## Troubleshooting ### Build Errors - **"Module not found"**: Ensure all dependencies are installed with `pnpm install` - **TypeScript errors**: Check [tsconfig.json](tsconfig.json) configuration - **Import path issues**: Verify file extensions are included in imports (`.js` for TypeScript files) ### Storybook Issues - **Port already in use**: Storybook runs on port 6006 by default. Stop other processes or change the port in the storybook script - **Components not updating**: Clear Storybook cache and rebuild ### Test Failures - **Browser not found**: Run `npx playwright install` to install test browsers - **Tests timing out**: Increase timeout in [web-test-runner.config.js](web-test-runner.config.js) ## Contributing Contributions are welcome! This project uses: - **Husky** for git hooks - **lint-staged** for pre-commit linting - **Prettier** for code formatting - **ESLint** for code quality Code is automatically formatted and linted on commit. ## License MIT