From bc86aa4054ada1b0dcac5a2fa6d6826a607c2597 Mon Sep 17 00:00:00 2001 From: Ashvin Tiwari Date: Mon, 10 Nov 2025 13:06:50 +0530 Subject: [PATCH] feat: add framework integration examples and documentation Add comprehensive documentation and working examples for integrating Gardevoir with modern JavaScript frameworks. Features added: - Complete framework integration guide covering React, Vue, Angular, Svelte - Working React example project with Vite configuration - Build tool configurations for Webpack, Vite, Rollup - Performance optimization guidelines - Troubleshooting section for common integration issues Benefits: - Helps developers integrate Gardevoir with modern workflows - Provides working examples that can be run and tested - Addresses common setup questions and configuration issues - Supports production-ready implementation patterns This addresses the gap between Gardevoir's excellent CSS reset functionality and practical usage in modern JavaScript applications. --- README.md | 29 + docs/framework-integration.md | 648 ++++++++++++++++++++++ examples/README.md | 39 ++ examples/react-integration/index.html | 14 + examples/react-integration/package.json | 20 + examples/react-integration/src/App.css | 266 +++++++++ examples/react-integration/src/App.jsx | 81 +++ examples/react-integration/src/main.jsx | 9 + examples/react-integration/vite.config.js | 15 + 9 files changed, 1121 insertions(+) create mode 100644 docs/framework-integration.md create mode 100644 examples/README.md create mode 100644 examples/react-integration/index.html create mode 100644 examples/react-integration/package.json create mode 100644 examples/react-integration/src/App.css create mode 100644 examples/react-integration/src/App.jsx create mode 100644 examples/react-integration/src/main.jsx create mode 100644 examples/react-integration/vite.config.js diff --git a/README.md b/README.md index 40cae0c..32ca864 100644 --- a/README.md +++ b/README.md @@ -134,3 +134,32 @@ Gardevoir as said, is a zero-dependency project and excels in integrating with a ## ❤ Thanks to our supporters [![GitHub Stargazers](https://reporoster.com/stars/krshoss/gardevoir)](https://github.com/krshoss/gardevoir/stargazers) + +## 🔧 Framework Integration + +Gardevoir works seamlessly with modern JavaScript frameworks. Check out our comprehensive integration guide and examples: + +- **[Framework Integration Guide](docs/framework-integration.md)** - Detailed setup instructions for React, Vue, Angular, and more +- **[Working Examples](examples/)** - Complete example projects you can run and learn from + +### Quick Framework Setup + +**React/Next.js:** +```jsx +import 'gardevoir'; +import './your-styles.css'; +``` + +**Vue/Nuxt.js:** +```js +// main.js or nuxt.config.js +import 'gardevoir'; +``` + +**Angular:** +```css +/* styles.css */ +@import 'gardevoir'; +``` + +For complete setup instructions, build configurations, and troubleshooting, see our [Framework Integration Guide](docs/framework-integration.md). diff --git a/docs/framework-integration.md b/docs/framework-integration.md new file mode 100644 index 0000000..15aa4a3 --- /dev/null +++ b/docs/framework-integration.md @@ -0,0 +1,648 @@ +# Framework Integration Guide for Gardevoir + +Modern web development relies heavily on JavaScript frameworks and build tools. This guide provides comprehensive examples and best practices for integrating Gardevoir with popular frameworks and build systems. + +## Table of Contents + +- [React & Next.js](#react--nextjs) +- [Vue & Nuxt.js](#vue--nuxtjs) +- [Angular](#angular) +- [Svelte & SvelteKit](#svelte--sveltekit) +- [Build Tools & Bundlers](#build-tools--bundlers) +- [Performance Optimization](#performance-optimization) +- [Troubleshooting](#troubleshooting) + +## React & Next.js + +### Standard React Application + +#### Installation +```bash +npm install gardevoir +# or +yarn add gardevoir +``` + +#### Method 1: Import in your main CSS file +```css +/* src/styles/globals.css or src/index.css */ +@import 'gardevoir'; + +/* Your custom styles go here */ +body { + font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; +} +``` + +#### Method 2: Import in your JavaScript entry point +```jsx +// src/index.js or src/App.js +import 'gardevoir'; +import './App.css'; // Your custom styles + +function App() { + return ( +
+

Hello Gardevoir!

+

CSS Reset is working perfectly!

+
+ ); +} + +export default App; +``` + +### Next.js Integration + +#### In `_app.js` (Recommended) +```jsx +// pages/_app.js +import 'gardevoir'; +import '../styles/globals.css'; + +export default function App({ Component, pageProps }) { + return ; +} +``` + +#### With CSS Modules +```jsx +// pages/_app.js +import 'gardevoir'; + +// components/Button.module.css +.button { + padding: 1rem 2rem; + border: none; + border-radius: 4px; + background: #007acc; + color: white; + cursor: pointer; +} + +// components/Button.js +import styles from './Button.module.css'; + +export default function Button({ children, ...props }) { + return ( + + ); +} +``` + +#### Server-Side Rendering (SSR) Considerations +```jsx +// next.config.js +const nextConfig = { + experimental: { + optimizeCss: true, // Optimize CSS delivery + }, + compiler: { + removeConsole: process.env.NODE_ENV === 'production', + }, +}; + +module.exports = nextConfig; +``` + +## Vue & Nuxt.js + +### Vue 3 with Vite + +#### Method 1: Import in main.js +```js +// src/main.js +import { createApp } from 'vue'; +import App from './App.vue'; +import 'gardevoir'; +import './style.css'; // Your custom styles + +createApp(App).mount('#app'); +``` + +#### Method 2: Import in style.css +```css +/* src/style.css */ +@import 'gardevoir'; + +/* Your Vue-specific styles */ +#app { + max-width: 1280px; + margin: 0 auto; + padding: 2rem; + text-align: center; +} +``` + +### Nuxt.js Integration + +#### Option 1: Global CSS (Recommended) +```js +// nuxt.config.js +export default { + css: [ + 'gardevoir', + '~/assets/css/main.css' // Your custom styles + ], + // ... other config +} +``` + +#### Option 2: Plugin Method +```js +// plugins/gardevoir.client.js +import 'gardevoir'; + +// nuxt.config.js +export default { + plugins: [ + { src: '~/plugins/gardevoir.client.js', mode: 'client' } + ] +} +``` + +### Scoped Styles Compatibility +```vue + + + + +``` + +## Angular + +### Installation & Setup +```bash +ng new my-app +cd my-app +npm install gardevoir +``` + +#### Method 1: Import in styles.css +```css +/* src/styles.css */ +@import 'gardevoir'; + +/* Your global styles */ +html, body { + height: 100%; +} + +body { + margin: 0; + font-family: Roboto, "Helvetica Neue", sans-serif; +} +``` + +#### Method 2: Angular CLI Configuration +```json +// angular.json +{ + "projects": { + "my-app": { + "architect": { + "build": { + "options": { + "styles": [ + "node_modules/gardevoir/gardevoir.min.css", + "src/styles.css" + ] + } + } + } + } + } +} +``` + +### Component-Level Integration +```typescript +// app.component.ts +import { Component } from '@angular/core'; + +@Component({ + selector: 'app-root', + template: ` +
+

Welcome to Angular with Gardevoir

+

CSS reset is working perfectly!

+
+ `, + styleUrls: ['./app.component.css'] +}) +export class AppComponent { + title = 'my-app'; +} +``` + +```css +/* app.component.css */ +.container { + max-width: 1200px; + margin: 0 auto; + padding: 2rem; +} + +h1 { + color: #1976d2; + text-align: center; +} +``` + +## Svelte & SvelteKit + +### SvelteKit Integration +```js +// app.html + + + + + + + %sveltekit.head% + + +
%sveltekit.body%
+ + +``` + +```css +/* src/app.css */ +@import 'gardevoir'; + +/* Your global styles */ +:root { + --primary-color: #ff3e00; + --text-color: #333; +} + +body { + color: var(--text-color); + font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; +} +``` + +```js +// src/app.js +import './app.css'; +import App from './App.svelte'; + +const app = new App({ + target: document.getElementById('app') +}); + +export default app; +``` + +### Svelte Component Example +```svelte + + + +
+

{title}

+

{content}

+
+ + +``` + +## Build Tools & Bundlers + +### Webpack Configuration +```js +// webpack.config.js +const path = require('path'); +const MiniCssExtractPlugin = require('mini-css-extract-plugin'); + +module.exports = { + entry: './src/index.js', + output: { + path: path.resolve(__dirname, 'dist'), + filename: 'bundle.js', + }, + module: { + rules: [ + { + test: /\.css$/, + use: [ + MiniCssExtractPlugin.loader, + 'css-loader' + ], + }, + ], + }, + plugins: [ + new MiniCssExtractPlugin({ + filename: 'styles.css', + }), + ], +}; +``` + +### Vite Configuration +```js +// vite.config.js +import { defineConfig } from 'vite'; + +export default defineConfig({ + css: { + preprocessorOptions: { + css: { + additionalData: `@import 'gardevoir';` + } + } + }, + build: { + cssCodeSplit: true, + rollupOptions: { + output: { + assetFileNames: (assetInfo) => { + if (assetInfo.name.endsWith('.css')) { + return 'assets/styles/[name]-[hash][extname]'; + } + return 'assets/[name]-[hash][extname]'; + } + } + } + } +}); +``` + +### Rollup Configuration +```js +// rollup.config.js +import css from 'rollup-plugin-css-only'; +import resolve from '@rollup/plugin-node-resolve'; + +export default { + input: 'src/main.js', + output: { + file: 'public/build/bundle.js', + format: 'iife', + name: 'app' + }, + plugins: [ + resolve({ + browser: true, + dedupe: ['svelte'] + }), + css({ output: 'bundle.css' }) + ] +}; +``` + +## Performance Optimization + +### CSS Purging with PurgeCSS +```js +// postcss.config.js +const purgecss = require('@fullhuman/postcss-purgecss'); + +module.exports = { + plugins: [ + ...(process.env.NODE_ENV === 'production' ? [purgecss({ + content: ['./src/**/*.{js,jsx,ts,tsx,vue,svelte,html}'], + defaultExtractor: content => content.match(/[\w-/:]+(? + + + +``` + +#### 4. CSS-in-JS Conflicts +**Problem**: Styled-components or emotion overriding reset styles +**Solution**: Use CSS reset with proper injection order + +```jsx +// styled-components with ThemeProvider +import styled, { createGlobalStyle } from 'styled-components'; + +const GlobalStyle = createGlobalStyle` + @import 'gardevoir'; + + /* Additional global styles */ + body { + font-family: ${props => props.theme.fontFamily}; + } +`; + +function App() { + return ( + + + {/* Your app components */} + + ); +} +``` + +### Performance Monitoring + +#### Bundle Analysis +```bash +# Analyze your bundle to see Gardevoir's impact +npm install --save-dev webpack-bundle-analyzer + +# Add to package.json +{ + "scripts": { + "analyze": "npm run build && npx webpack-bundle-analyzer build/static/js/*.js" + } +} +``` + +#### Lighthouse Integration Testing +```js +// Test performance impact with Lighthouse CI +// .lighthouserc.js +module.exports = { + ci: { + collect: { + url: ['http://localhost:3000'], + startServerCommand: 'npm run start', + }, + assert: { + assertions: { + 'categories:performance': ['warn', { minScore: 0.9 }], + 'categories:accessibility': ['error', { minScore: 0.9 }], + }, + }, + }, +}; +``` + +## Best Practices Summary + +### ✅ Do's +- Import Gardevoir before your custom styles +- Use build-time optimizations in production +- Test across different browsers and devices +- Monitor bundle size impact +- Use proper CSS loading strategies for SSR + +### ❌ Don'ts +- Don't override Gardevoir's core normalizations without good reason +- Don't load multiple CSS resets simultaneously +- Don't ignore build optimization opportunities +- Don't forget to test with your specific framework setup + +## Framework-Specific Performance Tips + +### React/Next.js +- Use `next/dynamic` for code splitting CSS-heavy components +- Implement proper preloading strategies +- Consider CSS Modules for component isolation + +### Vue/Nuxt.js +- Leverage Nuxt's automatic CSS optimization +- Use scoped styles appropriately +- Implement proper SSR CSS handling + +### Angular +- Use Angular CLI's built-in optimization features +- Implement OnPush change detection for better performance +- Consider lazy loading for large applications + +### Svelte/SvelteKit +- Take advantage of Svelte's compile-time optimizations +- Use SvelteKit's automatic code splitting +- Implement proper preloading strategies + +This integration guide ensures Gardevoir works seamlessly with modern development workflows while maintaining its performance benefits. \ No newline at end of file diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..ca76306 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,39 @@ +# Gardevoir Framework Integration Examples + +This directory contains practical examples showing how to integrate Gardevoir with popular JavaScript frameworks and build tools. + +## Available Examples + +### React Integration (`react-integration/`) +- Complete React application using Gardevoir +- Demonstrates proper import order and configuration +- Includes responsive design and component examples +- Shows build optimization with Vite + +## Running the Examples + +Each example is a complete, runnable project: + +```bash +cd examples/react-integration +npm install +npm run dev +``` + +## What These Examples Demonstrate + +1. **Proper Integration Patterns** - Correct way to import and use Gardevoir +2. **Build Tool Configuration** - Working configs for modern bundlers +3. **Performance Optimization** - How to minimize bundle impact +4. **Real-World Usage** - Practical components and layouts +5. **Cross-Browser Compatibility** - Gardevoir's benefits in action + +## Contributing More Examples + +If you'd like to contribute examples for other frameworks (Vue, Angular, Svelte, etc.), please follow the existing structure and ensure: + +- Complete, runnable project +- Clear documentation +- Performance considerations +- Responsive design examples +- Build configuration included diff --git a/examples/react-integration/index.html b/examples/react-integration/index.html new file mode 100644 index 0000000..dfeefea --- /dev/null +++ b/examples/react-integration/index.html @@ -0,0 +1,14 @@ + + + + + + + React + Gardevoir CSS Reset Example + + + +
+ + + \ No newline at end of file diff --git a/examples/react-integration/package.json b/examples/react-integration/package.json new file mode 100644 index 0000000..19c76c4 --- /dev/null +++ b/examples/react-integration/package.json @@ -0,0 +1,20 @@ +{ + "name": "gardevoir-react-example", + "version": "1.0.0", + "description": "Example React application using Gardevoir CSS Reset", + "private": true, + "dependencies": { + "react": "^18.2.0", + "react-dom": "^18.2.0", + "gardevoir": "latest" + }, + "devDependencies": { + "@vitejs/plugin-react": "^4.0.0", + "vite": "^4.4.0" + }, + "scripts": { + "dev": "vite", + "build": "vite build", + "preview": "vite preview" + } +} \ No newline at end of file diff --git a/examples/react-integration/src/App.css b/examples/react-integration/src/App.css new file mode 100644 index 0000000..2ff3504 --- /dev/null +++ b/examples/react-integration/src/App.css @@ -0,0 +1,266 @@ +/* Custom styles for React + Gardevoir example */ +/* Gardevoir is imported in App.jsx - this demonstrates proper loading order */ + +.app { + min-height: 100vh; + display: flex; + flex-direction: column; +} + +.app-header { + background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); + color: white; + padding: 3rem 2rem; + text-align: center; +} + +.app-header h1 { + font-size: 2.5rem; + margin: 0 0 1rem 0; + font-weight: 700; +} + +.subtitle { + font-size: 1.2rem; + opacity: 0.9; + margin: 0; +} + +.app-main { + flex: 1; + max-width: 1200px; + margin: 0 auto; + padding: 2rem; + width: 100%; +} + +.demo-section { + margin: 3rem 0; + padding: 2rem; + background: #f8f9fa; + border-radius: 8px; + border-left: 4px solid #667eea; +} + +.demo-section h2 { + color: #333; + margin: 0 0 1.5rem 0; + font-size: 1.8rem; +} + +.demo-section p { + line-height: 1.6; + color: #666; +} + +.demo-section ul { + color: #666; + line-height: 1.6; +} + +.demo-section li { + margin: 0.5rem 0; +} + +/* Form Styles */ +.demo-form { + max-width: 500px; +} + +.form-group { + margin: 1.5rem 0; +} + +.form-group label { + display: block; + margin-bottom: 0.5rem; + font-weight: 600; + color: #333; +} + +.form-group input, +.form-group textarea { + width: 100%; + padding: 0.75rem; + border: 2px solid #e1e5e9; + border-radius: 4px; + font-size: 1rem; + transition: border-color 0.2s ease; +} + +.form-group input:focus, +.form-group textarea:focus { + outline: none; + border-color: #667eea; + box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1); +} + +.submit-btn { + background: #667eea; + color: white; + border: none; + padding: 0.75rem 2rem; + border-radius: 4px; + font-size: 1rem; + font-weight: 600; + cursor: pointer; + transition: background-color 0.2s ease, transform 0.1s ease; +} + +.submit-btn:hover { + background: #5a67d8; + transform: translateY(-1px); +} + +.submit-btn:active { + transform: translateY(0); +} + +/* Button Styles */ +.button-group { + display: flex; + gap: 1rem; + flex-wrap: wrap; +} + +.btn { + padding: 0.75rem 1.5rem; + border-radius: 4px; + font-size: 1rem; + font-weight: 600; + cursor: pointer; + transition: all 0.2s ease; + border: 2px solid transparent; +} + +.btn-primary { + background: #667eea; + color: white; + border-color: #667eea; +} + +.btn-primary:hover { + background: #5a67d8; + border-color: #5a67d8; + transform: translateY(-1px); +} + +.btn-secondary { + background: #6c757d; + color: white; + border-color: #6c757d; +} + +.btn-secondary:hover { + background: #5a6268; + border-color: #5a6268; + transform: translateY(-1px); +} + +.btn-outline { + background: transparent; + color: #667eea; + border-color: #667eea; +} + +.btn-outline:hover { + background: #667eea; + color: white; + transform: translateY(-1px); +} + +/* Card Grid */ +.card-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); + gap: 2rem; + margin-top: 2rem; +} + +.card { + background: white; + padding: 2rem; + border-radius: 8px; + box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1); + border: 1px solid #e1e5e9; + transition: transform 0.2s ease, box-shadow 0.2s ease; +} + +.card:hover { + transform: translateY(-2px); + box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15); +} + +.card h3 { + margin: 0 0 1rem 0; + color: #333; + font-size: 1.3rem; +} + +.card p { + margin: 0; + line-height: 1.6; + color: #666; +} + +/* Footer */ +.app-footer { + background: #2d3748; + color: white; + text-align: center; + padding: 2rem; + margin-top: 4rem; +} + +.app-footer p { + margin: 0.5rem 0; + opacity: 0.8; +} + +/* Responsive Design */ +@media (max-width: 768px) { + .app-header { + padding: 2rem 1rem; + } + + .app-header h1 { + font-size: 2rem; + } + + .app-main { + padding: 1rem; + } + + .demo-section { + padding: 1.5rem; + margin: 2rem 0; + } + + .button-group { + flex-direction: column; + } + + .btn { + width: 100%; + } + + .card-grid { + grid-template-columns: 1fr; + gap: 1rem; + } +} + +/* Demonstrating that Gardevoir's reset doesn't interfere with custom styles */ +@media (max-width: 480px) { + .app-header h1 { + font-size: 1.8rem; + } + + .subtitle { + font-size: 1rem; + } + + .demo-section h2 { + font-size: 1.5rem; + } +} \ No newline at end of file diff --git a/examples/react-integration/src/App.jsx b/examples/react-integration/src/App.jsx new file mode 100644 index 0000000..19593a8 --- /dev/null +++ b/examples/react-integration/src/App.jsx @@ -0,0 +1,81 @@ +import React from 'react'; +// Import Gardevoir CSS Reset first +import 'gardevoir'; +// Then import custom styles +import './App.css'; + +function App() { + return ( +
+
+

Gardevoir + React Integration

+

Modern CSS Reset working perfectly with React

+
+ +
+
+

Typography Demo

+

This paragraph demonstrates how Gardevoir normalizes text rendering across browsers while maintaining readability.

+
    +
  • List items have consistent spacing
    • +
  • Cross-browser normalization applied
    • +
  • No unexpected margins or padding
    • +
+
+ +
+

Form Elements

+
+
+ + +
+
+ + +
+
+ + +
+ +
+
+ +
+

Interactive Elements

+
+ + + +
+
+ +
+

Layout Elements

+
+
+

Card Title 1

+

Card content with consistent spacing and typography thanks to Gardevoir's normalization.

+
+
+

Card Title 2

+

Another card showing how the reset maintains consistency across different elements.

+
+
+

Card Title 3

+

Third card demonstrating reliable cross-browser rendering.

+
+
+
+
+ +
+

Built with React + Gardevoir CSS Reset

+

Gardevoir provides consistent styling across all browsers

+
+
+ ); +} + +export default App; \ No newline at end of file diff --git a/examples/react-integration/src/main.jsx b/examples/react-integration/src/main.jsx new file mode 100644 index 0000000..9657af5 --- /dev/null +++ b/examples/react-integration/src/main.jsx @@ -0,0 +1,9 @@ +import React from 'react'; +import ReactDOM from 'react-dom/client'; +import App from './App.jsx'; + +ReactDOM.createRoot(document.getElementById('root')).render( + + + +); \ No newline at end of file diff --git a/examples/react-integration/vite.config.js b/examples/react-integration/vite.config.js new file mode 100644 index 0000000..7cdf1ed --- /dev/null +++ b/examples/react-integration/vite.config.js @@ -0,0 +1,15 @@ +import { defineConfig } from 'vite' +import react from '@vitejs/plugin-react' + +export default defineConfig({ + plugins: [react()], + server: { + port: 3000, + open: true + }, + build: { + outDir: 'dist', + assetsDir: 'assets', + sourcemap: true + } +}) \ No newline at end of file