lit/mycomponents/README.md

MyComponents

A framework-agnostic UI component library built with TypeScript, TailwindCSS v4, and Alpine.js. This package is designed for maximum compatibility and ease of use in any modern frontend stack, including React, Vue, Laravel, and plain HTML.

Table of Contents

• Project Structure
• Getting Started
• Editing & Adding Features
  • Adding New Components
  • Using TailwindCSS & Alpine.js
  • TypeScript Best Practices
• Building & Development
• Deploying & Publishing
• Consuming in Other Frameworks
  • React
  • Vue
  • Laravel & Blade
  • Plain HTML/JS
• Troubleshooting
• References

Project Structure

mycomponents/
├── dist/                # Build output
├── src/
│   ├── index.ts         # Entry point, exports components
│   ├── style.css        # TailwindCSS entry
│   └── index.html       # Demo HTML
├── package.json
├── postcss.config.js
├── tailwind.config.js
├── webpack.config.ts
├── tsconfig.json
└── README.md

Getting Started

1. Install dependencies:

   npm install

2. Development mode (hot reload):

   npm run dev

   Visit http://localhost:3000 to see the demo.

3. Production build:

   npm run build

Editing & Adding Features

Adding New Components

1. Create a new TypeScript file in src/
   Example: src/my-button.ts

   export class MyButton extends HTMLElement {
     connectedCallback() {
       this.innerHTML = `
         <button class="bg-green-500 text-white px-4 py-2 rounded" @click="alert('Clicked!')">
           <slot>Click Me</slot>
         </button>
       `;
       window.Alpine && window.Alpine.initTree(this);
     }
   }
   if (!customElements.get('my-button')) {
     customElements.define('my-button', MyButton);
   }

2. Export your component in src/index.ts:

   export * from './my-button';

3. Use Tailwind utility classes and Alpine.js directives as needed.

Using TailwindCSS & Alpine.js

• TailwindCSS:
  Use utility classes directly in your component templates.
• Alpine.js:
  Use x-data, x-show, @click, etc. Alpine is globally available.

TypeScript Best Practices

• Use strict types for all custom elements.
• Use declare global for extending the window object if needed.
• Always check if a custom element is already defined before registering.

Building & Development

• Development:
  npm run dev (Webpack dev server, hot reload)
• Production:
  npm run build (Outputs to dist/)
• Type checking:
  npm run typecheck

Deploying & Publishing

1. Login to npm (if not already):

   npm login

2. Publish:

   npm publish --access public

3. After publishing:
   Your package can be installed via npm in any project.

Consuming in Other Frameworks

React

1. Install the package:

   npm install mycomponents

2. Import the bundle in your entry file (e.g., index.tsx):

   import 'mycomponents/dist/bundle.js';
   import 'mycomponents/dist/bundle.css'; // If you extract CSS separately

3. Use the custom element in JSX:

   <my-toggle></my-toggle>

   Note: For TypeScript, add a declaration for custom elements:

   declare namespace JSX {
     interface IntrinsicElements {
       'my-toggle': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
     }
   }

Vue

1. Install and import as above.
2. Use in templates:

   <my-toggle></my-toggle>

Laravel & Blade

1. Install via npm/yarn.
2. Include the bundle in your Blade template:

   <script src="{{ mix('node_modules/mycomponents/dist/bundle.js') }}"></script>
   <link rel="stylesheet" href="{{ mix('node_modules/mycomponents/dist/bundle.css') }}">
   <my-toggle></my-toggle>

Plain HTML/JS

1. Include the bundle via CDN or local build:

   <script src="path/to/bundle.js"></script>
   <link rel="stylesheet" href="path/to/bundle.css">
   <my-toggle></my-toggle>

Troubleshooting

• TailwindCSS not working?
  Ensure you are using the correct PostCSS plugin: @tailwindcss/postcss.
• Custom elements not rendering?
  Make sure the bundle is loaded before using the elements.
• TypeScript errors for custom elements in React?
  Add a JSX namespace declaration as shown above.
• Alpine.js not working?
  Ensure window.Alpine is available and initTree is called in your component.

References

• TailwindCSS v4 Announcement
• Alpine.js Documentation
• Web Components Guide
• TypeScript Custom Elements
• PostCSS Plugin Migration

Happy hacking!
Feel free to open issues or PRs for improvements.