Merge pull request #323 from codomposer/fix/doc_development

add development.md to docs
1 month ago · af6e6df126
--- a/docs/getting-started/development.md
+++ b/docs/getting-started/development.md
@ -0,0 +1,462 @@
 # Development Workflow

 This guide covers the development workflow for working with Adminator, including running the development server, making changes, and best practices.

 ## Table of Contents

 - Quick Start
 - Development Server
 - Available npm Scripts
 - Making Changes
 - Hot Module Replacement
 - Code Quality & Linting
 - Debugging
 - Working with Components
 - Working with Styles
 - Best Practices
 - Common Issues
 - Next Steps

 ## Quick Start

 After [installation](installation.md), start the development server:

 ```bash
 npm start
 ```

 Your application will be available at **http://localhost:4000**

 ## Development Server

 ### Standard Development Server

 The standard development server includes hot module replacement (HMR) for instant updates:

 ```bash
 npm start
 ```

 **Features:**
 - Hot module replacement (HMR)
 - Automatic browser refresh
 - Source maps for debugging
 - Fast rebuild times
 - Runs on port 4000

 ### Development Server with Dashboard

 For enhanced development experience with visual feedback:

 ```bash
 npm run dev
 ```

 **Additional Features:**
 - Visual webpack dashboard
 - Real-time build statistics
 - Bundle size analysis
 - Build time metrics
 - Module dependency graph

 ## Available npm Scripts

 ### Development

 | Command | Description |
 |---------|-------------|
 | `npm start` | Start development server with HMR |
 | `npm run dev` | Start development server with webpack dashboard |
 | `npm run clean` | Clean the `dist/` directory |

 ### Production Build

 | Command | Description |
 |---------|-------------|
 | `npm run build` | Production build (optimized, minified) |
 | `npm run release:minified` | Production build with minification |
 | `npm run release:unminified` | Production build without minification (for debugging) |
 | `npm run preview` | Preview production build locally |

 ### Code Quality

 | Command | Description |
 |---------|-------------|
 | `npm run lint` | Run all linters (JavaScript + SCSS) |
 | `npm run lint:js` | Lint JavaScript files with ESLint |
 | `npm run lint:scss` | Lint SCSS files with Stylelint |

 ## Making Changes

 ### File Watching

 The development server automatically watches for changes in:

 - **HTML files** (`src/*.html`)
 - **JavaScript files** (`src/assets/scripts/**/*.js`)
 - **SCSS files** (`src/assets/styles/**/*.scss`)
 - **Static assets** (`src/assets/static/**/*`)

 Changes are automatically compiled and the browser refreshes.

 ### Workflow

 1. **Start the development server**
   ```bash
   npm start
   ```

 2. **Make your changes** in the `src/` directory

 3. **Save the file** - Changes are automatically detected

 4. **Browser refreshes** - See your changes instantly

 ## Hot Module Replacement (HMR)

 HMR allows modules to be updated without a full page reload, preserving application state.

 ### What Gets Hot Reloaded?

 - ✅ **JavaScript modules** - Component updates without page reload
 - ✅ **SCSS/CSS** - Style updates without page reload
 - ⚠️ **HTML files** - Requires full page reload
 - ⚠️ **Configuration files** - Requires server restart

 ### HMR Benefits

 - Faster development cycle
 - Preserves application state
 - Instant visual feedback
 - Better debugging experience

 ## Code Quality & Linting

 ### JavaScript Linting (ESLint)

 Adminator uses ESLint 9.x with flat configuration:

 ```bash
 # Lint all JavaScript files
 npm run lint:js

 # Auto-fix issues (if possible)
 npx eslint ./src --fix
 ```

 **Configuration:** `eslint.config.mjs`

 **Rules:**
 - ES6+ modern JavaScript
 - No jQuery patterns
 - Consistent code style
 - Import/export validation

 ### SCSS Linting (Stylelint)

 Maintain consistent SCSS code style:

 ```bash
 # Lint all SCSS files
 npm run lint:scss

 # Auto-fix issues (if possible)
 npx stylelint "./src/**/*.scss" --fix
 ```

 **Configuration:** `.stylelintrc.json`

 ### Running All Linters

 ```bash
 npm run lint
 ```

 This runs both JavaScript and SCSS linters in sequence.

 ## Debugging

 ### Source Maps

 Development builds include source maps for easier debugging:

 1. Open browser DevTools (F12)
 2. Navigate to Sources tab
 3. Find your original source files under `webpack://`
 4. Set breakpoints and debug as normal

 ### Console Logging

 The application includes minimal console output in production. For development debugging:

 ```javascript
 // Development-only logging
 if (process.env.NODE_ENV !== 'production') {
  console.log('Debug info:', data);
 }
 ```

 ### Browser DevTools

 **Recommended Extensions:**
 - React Developer Tools (if using React components)
 - Vue.js devtools (if using Vue components)
 - Redux DevTools (if using Redux)

 ## Working with Components

 ### Creating a New Component

 1. **Create component file** in `src/assets/scripts/components/`:

 ```javascript
 // src/assets/scripts/components/MyComponent.js
 class MyComponent {
  constructor(element) {
    this.element = element;
    this.init();
  }

  init() {
    // Initialize component
    this.setupEventListeners();
  }

  setupEventListeners() {
    // Add event listeners
  }

  destroy() {
    // Cleanup
  }
 }

 export default MyComponent;
 ```

 2. **Import and use** in `app.js`:

 ```javascript
 import MyComponent from '@/components/MyComponent';

 // Initialize
 const myComponent = new MyComponent(document.querySelector('.my-component'));
 ```

 3. **Add component styles** in `src/assets/styles/spec/components/`:

 ```scss
 // src/assets/styles/spec/components/myComponent.scss
 .my-component {
  // Component styles
 }
 ```

 4. **Import styles** in `src/assets/styles/spec/components/index.scss`:

 ```scss
@import 'myComponent';
 ```

 ### Component Best Practices

 - Use ES6 classes for components
 - Keep components focused and single-purpose
 - Implement `destroy()` method for cleanup
 - Use webpack aliases (`@/components`, `@/utils`)
 - Follow existing naming conventions

 ## Working with Styles

 ### SCSS Architecture

 Adminator follows ITCSS (Inverted Triangle CSS) methodology:

 ```
 styles/
 ├── settings/    # Variables, config
 ├── tools/       # Mixins, functions
 ├── generic/     # Reset, normalize
 ├── components/  # UI components
 ├── utils/       # Utility classes
 └── vendor/      # Third-party styles
 ```

 ### Adding New Styles

 1. **Component styles** → `src/assets/styles/spec/components/`
 2. **Page-specific styles** → `src/assets/styles/spec/screens/`
 3. **Utility classes** → `src/assets/styles/spec/utils/`

 ### Using CSS Variables

 Adminator uses CSS custom properties for theming:

 ```scss
 .my-component {
  background: var(--c-bkg-card);
  color: var(--c-text-base);
  border: 1px solid var(--c-border);
 }
 ```

 **Available variables:** See `src/assets/styles/spec/utils/theme.css`

 ### Dark Mode Support

 Ensure your components support dark mode:

 ```scss
 .my-component {
  background: var(--c-bkg-card); // Auto-adjusts for dark mode
  
  // Or use data attribute
  [data-theme="dark"] & {
    background: #1f2937;
  }
 }
 ```

 ## Best Practices

 ### Code Organization

 - ✅ Keep files small and focused
 - ✅ Use meaningful file and variable names
 - ✅ Group related functionality
 - ✅ Follow existing project structure
 - ✅ Use webpack aliases for imports

 ### JavaScript

 - ✅ Use modern ES6+ features
 - ✅ Avoid jQuery patterns
 - ✅ Use vanilla JavaScript DOM APIs
 - ✅ Implement proper error handling
 - ✅ Add JSDoc comments for complex functions

 ### SCSS

 - ✅ Use variables for colors and spacing
 - ✅ Follow BEM naming convention (optional)
 - ✅ Keep selectors shallow (max 3 levels)
 - ✅ Use mixins for repeated patterns
 - ✅ Support dark mode with CSS variables

 ### Performance

 - ✅ Minimize DOM manipulations
 - ✅ Use event delegation
 - ✅ Debounce/throttle frequent events
 - ✅ Lazy load heavy components
 - ✅ Optimize images and assets

 ### Accessibility

 - ✅ Use semantic HTML
 - ✅ Add ARIA labels where needed
 - ✅ Ensure keyboard navigation
 - ✅ Maintain color contrast ratios
 - ✅ Test with screen readers

 ## Common Issues

 ### Port Already in Use

 If port 4000 is already in use:

 ```bash
 # Kill the process using port 4000 (Windows)
 netstat -ano | findstr :4000
 taskkill /PID <PID> /F

 # Or change the port in webpack/devServer.js
 ```

 ### Changes Not Reflecting

 1. **Hard refresh** the browser (Ctrl+F5)
 2. **Clear browser cache**
 3. **Restart development server**
 4. **Check for JavaScript errors** in console
 5. **Verify file is being watched** (check terminal output)

 ### Build Errors

 ```bash
 # Clean and rebuild
 npm run clean
 npm install
 npm start
 ```

 ### Linting Errors

 ```bash
 # Auto-fix common issues
 npx eslint ./src --fix
 npx stylelint "./src/**/*.scss" --fix

 # Check remaining issues
 npm run lint
 ```

 ### Module Not Found

 ```bash
 # Reinstall dependencies
 rm -rf node_modules package-lock.json
 npm install
 ```

 ## Development Tips

 ### 1. Use the Webpack Dashboard

 ```bash
 npm run dev
 ```

 Provides visual feedback on build performance and bundle size.

 ### 2. Keep the Console Clean

 Fix warnings and errors as they appear to maintain code quality.

 ### 3. Test in Multiple Browsers

 - Chrome/Edge (Chromium)
 - Firefox
 - Safari (if on macOS)
 - Mobile browsers (responsive mode)

 ### 4. Use Browser DevTools

 - **Elements tab** - Inspect and modify DOM/CSS
 - **Console tab** - Debug JavaScript
 - **Network tab** - Monitor requests
 - **Performance tab** - Profile performance
 - **Application tab** - Check localStorage/theme

 ### 5. Commit Often

 Make small, focused commits with clear messages:

 ```bash
 git add .
 git commit -m "feat: add new dashboard widget"
 git push
 ```

 ## Next Steps

 Now that you understand the development workflow:

 1. **[Customize Themes](../customization/theme-system.md)** - Set up dark mode and theming
 2. **[Build for Production](build-deployment.md)** - Deploy your application
 3. **[API Reference](../api/theme-api.md)** - JavaScript API documentation
 4. **[Project Structure](project-structure.md)** - Review the codebase structure

 ---

 **Need Help?** Check the [main README](../../README.md) or [open an issue](https://github.com/puikinsh/Adminator-admin-dashboard/issues).