@mapvx/website-component 0.5.0 → 0.5.3

package/README.md

@@ -52,29 +52,95 @@ import '@mapvx/website-component/dist/browser/styles.css'
 ```jsx
 // In your main App.jsx or index.jsx
 import '@mapvx/website-component/dist/browser/main.js'
-import '@mapvx/website-component/dist/browser/styles.css'
 
 function App() {
   return <mapvx-website api-key="your-api-key-here" />
 }
 ```
 
+```css
+/* In your main CSS file (e.g., index.css, App.css) */
+@import '@mapvx/website-component/dist/browser/styles.css';
+```
+
 **Vue:**
 
 ```javascript
 // In your main.js
 import '@mapvx/website-component/dist/browser/main.js'
-import '@mapvx/website-component/dist/browser/styles.css'
+```
+
+```css
+/* In your main CSS file (e.g., style.css, main.css) */
+@import '@mapvx/website-component/dist/browser/styles.css';
 ```
 
 **Angular:**
 
+#### Method 1: HTML Script Tags
+
+Configure assets in `angular.json` and use script tags in `index.html`:
+
+```json
+{
+  "assets": [
+    {
+      "glob": "**/*",
+      "input": "public"
+    },
+    {
+      "glob": "**/*",
+      "input": "src/assets",
+      "output": "assets"
+    },
+    {
+      "glob": "**/*",
+      "input": "node_modules/@mapvx/website-component/dist/browser",
+      "output": "website-component"
+    }
+  ]
+}
+```
+
+Then reference the files in your `index.html`:
+
+```html
+<!-- Web Component Scripts -->
+<script src="website-component/main.js" defer></script>
+
+<!-- Web Component Styles -->
+<link rel="stylesheet" href="website-component/styles.css" />
+```
+
+**Why this configuration is needed:**
+
+- Angular doesn't serve files from `node_modules` by default in development
+- Without proper asset configuration, you'll get `SyntaxError: Unexpected token '<'` errors
+- This ensures files are served as static assets with proper caching headers
+
+#### Method 2: TypeScript Imports
+
+Alternatively, you can import the files in your application:
+
 ```typescript
-// In your angular.json or import in main.ts
+// In your main.ts - Import the JavaScript
 import '@mapvx/website-component/dist/browser/main.js'
-import '@mapvx/website-component/dist/browser/styles.css'
 ```
 
+```scss
+/* In your styles.scss - Import the styles (Modern Sass) */
+@use '@mapvx/website-component/dist/browser/styles.css';
+
+/* Alternative for older Sass versions or CSS files */
+@import '@mapvx/website-component/dist/browser/styles.css';
+```
+
+**Important**: Choose ONE method only:
+
+- ✅ **Method 1**: HTML script tags + assets configuration
+- ✅ **Method 2**: TypeScript imports + SCSS imports
+- ❌ **Don't use both**: This can cause duplicate loading and conflicts
+
 ### Helper Package (SSR Support)
 
 For Server-Side Rendering (SSR) applications that need to preload initial data on the server:
@@ -433,6 +499,36 @@ function App() {
 - The web component will automatically pick up these custom colors
 - Use valid CSS color values (hex, rgb, hsl, etc.)
 
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### `SyntaxError: Unexpected token '<'` in Angular
+
+**Problem**: Angular returns HTML instead of JavaScript files from `node_modules`.
+
+**Solution**: Configure assets in `angular.json` as shown in the Angular Configuration section above.
+
+#### Slow Loading (>10 seconds)
+
+**Problem**: Large bundle size or incorrect asset serving.
+
+**Solutions**:
+
+- Use the recommended Angular assets configuration
+- Ensure files are served as static assets, not through routing
+- Check network tab in DevTools for 404 errors
+
+#### Web Component Not Loading
+
+**Problem**: Scripts not loading or component not registering.
+
+**Solutions**:
+
+- Verify file paths are correct
+- Check browser console for errors
+- Ensure `defer` attribute is used for script tags
+
 ## 🏠 Homepage
 
 Visit [MapVX](https://mapvx.com) for more information.