🔧 Common Issues #

Solutions to frequently encountered problems when working with Admindek VanillaJS.

Installation Issues #

Node.js Version Compatibility #

Problem: Error messages during npm install about unsupported Node.js version.

error @rollup/rollup-linux-x64-gnu@4.9.4: The engine "node" is incompatible with this module.

Solution:

1. Check your Node.js version:

   node --version

2. Use Node.js 20.19+ or 22.12+ (24 LTS recommended):

   # Using Node Version Manager (recommended)
   nvm install 24
   nvm use 24
    
   # Or download from nodejs.org

3. Clear cache and reinstall:

   npm ci

Package Installation Failures #

Problem: npm install fails with permission errors or missing packages.

EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Solutions:

Option 1 - Use npm prefix (Recommended):

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Option 2 - Fix permissions:

sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Option 3 - Use Yarn instead:

npm install -g yarn
yarn install
yarn dev

Build Errors #

Vite Configuration Issues #

Problem: Build fails with configuration errors.

[vite] Internal server error: Failed to resolve entry for package "admindek"

Solutions:

1. Check vite.config.js syntax:

   // Verify all imports exist
   import { defineConfig } from 'vite'
   import { vitePluginHtmlTemplates } from './plugins/vite-plugin-html-templates.js'
    
   // Check file paths are correct
   export default defineConfig({
     // Valid configuration
   })

2. Verify plugin files exist:

   ls -la plugins/
   # Should show: vite-plugin-html-templates.js, vite-plugin-copy-assets.js

3. Clear Vite cache:

   rm -rf node_modules/.vite
   npm run build

SCSS Compilation Errors #

Problem: SCSS files fail to compile with import errors.

Error: Can't find stylesheet to import.
@import "bootstrap/scss/bootstrap";

Solutions:

1. Check Bootstrap installation:

   npm list bootstrap
   # Should show bootstrap@5.3.8 or similar

2. Verify SCSS import paths:

   // In style.scss - check these imports exist
   @import 'bootstrap/scss/bootstrap';
   @import 'settings/theme-variables';
   @import 'themes/general';

3. Check file structure:

   ls src/assets/scss/settings/
   # Should contain _theme-variables.scss, _bootstrap-variables.scss

4. Clear SCSS cache:

   rm -rf dist/
   npm run build

Development Server Issues #

Port Already in Use #

Problem: Development server can't start because port is occupied.

Port 3000 is already in use

Solutions:

1. Kill process using the port:

   # Find process using port 3000
   lsof -ti :3000
    
   # Kill the process (replace PID with actual number)
   kill -9 PID
    
   # Or kill all Node processes (be careful!)
   killall node

2. Use different port:

   npm run preview -- --port 3001

3. Configure default port in vite.config.js:

   export default defineConfig({
     server: {
       port: 3001
     }
   })

Raw @@include Directives on a Page #

Source HTML files require template processing. Start Vite with npm run dev and open http://localhost:3000/forms/form2_flu-uppy.html for the upload demo. Opening src/html/ files directly, or using a generic static server, cannot resolve includes. Use npm run build followed by npm run preview to view production output.

Vite redirects /src/html/... and /dist/... page URLs to their public routes. If the server returns a template-processing error, check its terminal log for the missing include or circular include path.

Changes Not Appearing #

npm run dev watches HTML templates and shared layouts and reloads the page. It also recopies shared scripts when they change. Compiled CSS, feature bundles such as Uppy, and copied vendor assets are served from dist/; run npm run build after changing those files, then refresh. The preview server always serves the last build and does not watch source files.

Styling Issues #

CSS Not Loading #

Problem: Styles don't appear on the page or look broken.

Symptoms:

• Unstyled HTML elements
• Bootstrap styles not applied
• Custom styles missing

Solutions:

1. Check CSS includes in HTML templates:

   <!-- In head-css.html -->
   @@include('../layouts/head-css.html')
    
   <!-- Should generate links to CSS files -->
   <link rel="stylesheet" href="../assets/css/style.css">

2. Verify build output:

   ls dist/assets/css/
   # Should contain style.css and other CSS files

3. Check console for CSS errors:

   Open browser DevTools → Console → Look for 404 errors
   Failed to load resource: net::ERR_FILE_NOT_FOUND

4. Clear browser cache:

   # Hard refresh in browser
   Ctrl+Shift+R (Chrome/Firefox)
   Cmd+Shift+R (Safari)

Icons Not Displaying #

Problem: Phosphor or Tabler icons show as squares or don't appear.

Solutions:

1. Check icon font files:

   ls dist/assets/fonts/
   # Should contain phosphor/ and tabler/ folders

2. Verify CSS includes:

   <!-- Should be in head-css.html -->
   <link rel="stylesheet" href="../assets/fonts/phosphor/regular/style.css">
   <link rel="stylesheet" href="../assets/fonts/tabler-icons.min.css">

3. Check icon syntax:

   <!-- Phosphor icons (correct) -->
   <i class="ph-duotone ph-house"></i>
    
   <!-- Tabler icons (correct) -->
   <i class="ti ti-home"></i>
    
   <!-- Common mistakes -->
   <i class="ph ph-house"></i> <!-- Missing 'duotone' -->
   <i class="ph-house"></i>    <!-- Missing 'ph-duotone' -->

4. Test icon loading:

   /* Add to test CSS loading */
   .ph-duotone:before {
     content: "✓"; /* Should show checkmark if CSS loaded */
   }

Theme Variables Not Working #

Problem: CSS custom properties or theme colors don't apply.

Solutions:

1. Check theme configuration:

   // In vite.config.js
   const preset_theme = 'preset-1' // Should match desired theme
   const dark_layout = 'false'     // Should match desired mode

2. Verify CSS custom properties:

   /* Check if these exist in browser DevTools */
   :root {
     --bs-primary: #4f46e5;
     --pc-sidebar-bg: #1f2937;
   }

3. Check body attributes:

   <!-- Should be generated by @@bodySetup -->
   <body data-pc-preset="preset-1" data-pc-theme="light">

4. Browser compatibility:

   // Check if CSS custom properties are supported
   if (window.CSS && CSS.supports('color', 'var(--fake)')) {
     console.log('CSS custom properties supported');
   } else {
     console.log('CSS custom properties NOT supported');
   }

JavaScript Issues #

Charts Not Rendering #

Problem: Charts don't display.

Symptoms:

• Empty chart containers
• Chart is not defined or AdmindekChart is not defined in the console
• Canvas is already in use. Chart with ID '0' must be destroyed before the canvas with ID '' can be reused.
• A chart that is 0px tall, or one that only appears after resizing the window

Solutions:

1. Check that Chart.js and the theme preset loaded:

   // In browser console
   console.log(typeof Chart);         // "function" - chart.umd.min.js loaded
   console.log(typeof AdmindekChart); // "object"   - chart-theme.js loaded

   If either is "undefined", look in the Network tab for a 404 on assets/js/plugins/chart.umd.min.js or assets/js/chart-theme.js. The vendor file is copied from node_modules by the build, so run npm install and rebuild if it is missing from dist/assets/js/plugins/.

2. Check script loading order:

   <!-- Chart.js first, then any Chart.js plugins, then the theme preset, then the page script -->
   <script src="../assets/js/plugins/chart.umd.min.js"></script>
   <script src="../assets/js/chart-theme.js"></script>
   <script src="../assets/js/widgets/bar-chart.js"></script>

   chart-theme.js does nothing if Chart is not defined yet, so AdmindekChart will be missing when the order is wrong. Pages in the root folder (such as index.html) use assets/js/... without the ../.

3. Verify the chart container exists:

   const container = document.querySelector('#chart-id');
   console.log(container); // Should not be null

   AdmindekChart.create() returns null when the target is missing, so a typo in the selector fails silently.

4. Make sure the container has a height:

   // Give the chart a fixed height (sets it on the container)
   AdmindekChart.create('#chart-id', config, { height: 300 });

   If you set maintainAspectRatio: false yourself, the container needs a height from CSS or from the height option; otherwise the canvas is 0px tall. Charts inside Bootstrap tabs, modals, collapses and offcanvas panels are resized automatically when those are shown.

5. "Canvas is already in use": This happens when new Chart() is called twice on the same <canvas> (for example when re-rendering after new data arrives). Create charts with AdmindekChart.create(), which destroys the previous chart in that container first, or update the existing instance instead:

   const chart = AdmindekChart.create('#chart-id', config, { height: 300 });
    
   // Later: update in place instead of creating a new chart
   chart.data.datasets[0].data = newData;
   chart.update();
    
   // Or remove it completely
   chart.destroy();

6. Debug chart initialization:

   document.addEventListener('DOMContentLoaded', function () {
     const chartElement = document.querySelector('#chart-id');
     console.log('Chart element:', chartElement);
    
     if (chartElement && typeof AdmindekChart !== 'undefined') {
       // Chart initialization code
     } else {
       console.error('Chart requirements not met');
     }
   });

Form Validation Not Working #

Problem: Form validation doesn't trigger or show errors.

Solutions:

1. Check Bootstrap validation classes:

   <!-- Correct validation markup -->
   <form class="needs-validation" novalidate>
     <div class="mb-3">
       <input type="email" class="form-control" required>
       <div class="invalid-feedback">
         Please enter a valid email.
       </div>
     </div>
   </form>

2. Verify JavaScript validation:

   // Bootstrap validation initialization
   (function() {
     'use strict';
     var forms = document.querySelectorAll('.needs-validation');
     Array.prototype.slice.call(forms).forEach(function(form) {
       form.addEventListener('submit', function(event) {
         if (!form.checkValidity()) {
           event.preventDefault();
           event.stopPropagation();
         }
         form.classList.add('was-validated');
       }, false);
     });
   })();

3. Check form submission:

   // Debug form validation
   document.querySelectorAll('form').forEach(form => {
     form.addEventListener('submit', function(e) {
       console.log('Form submitted:', form);
       console.log('Valid:', form.checkValidity());
     });
   });

Navigation Issues #

Sidebar Menu Not Working #

Problem: Sidebar navigation doesn't expand/collapse or links don't work.

Solutions:

1. Check Bootstrap JavaScript:

   <!-- Ensure Bootstrap JS is loaded -->
   <script src="../assets/js/plugins/bootstrap.min.js"></script>

2. Verify menu HTML structure:

   <!-- Correct dropdown structure -->
   <li class="pc-item pc-hasmenu">
     <a href="#!" class="pc-link">
       <span class="pc-mtext">Dashboard</span>
       <span class="pc-arrow"><i data-feather="chevron-right"></i></span>
     </a>
     <ul class="pc-submenu">
       <li class="pc-item">
         <a class="pc-link" href="../dashboard/analytics.html">Analytics</a>
       </li>
     </ul>
   </li>

3. Check active menu highlighting:

   // Debug active menu detection
   const currentPath = window.location.pathname;
   console.log('Current path:', currentPath);
    
   document.querySelectorAll('.pc-link').forEach(link => {
     if (link.getAttribute('href').includes(currentPath)) {
       console.log('Should be active:', link);
     }
   });

Breadcrumb Issues #

Problem: Breadcrumbs show incorrect paths or don't update.

Solutions:

1. Check breadcrumb template usage:

   <!-- Correct breadcrumb include -->
   @@include('../layouts/breadcrumb.html', {
     'breadcrumb-item': 'Dashboard',
     'breadcrumb-item-active': 'Analytics'
   })

2. Verify breadcrumb.html template:

   <!-- In layouts/breadcrumb.html -->
   <div class="page-header">
     <div class="page-block">
       <div class="row align-items-center">
         <div class="col-md-12">
           <div class="page-header-title">
             <h2 class="mb-0">@@breadcrumb-item-active</h2>
           </div>
           <ul class="breadcrumb">
             <li class="breadcrumb-item">
               <a href="../dashboard/index.html">@@breadcrumb-item</a>
             </li>
             <li class="breadcrumb-item active">@@breadcrumb-item-active</li>
           </ul>
         </div>
       </div>
     </div>
   </div>

Performance Issues #

Slow Page Loading #

Problem: Pages take too long to load.

Diagnosis Steps:

1. Check Network tab in DevTools:

   • Look for large file sizes (>1MB)
   • Check for failed requests (404s)
   • Identify slow-loading resources

2. Common causes and solutions:

Large Bundle Sizes:

# Analyze bundle size
npm run build -- --analyze
 
# Check dist folder size
du -sh dist/

Unused Dependencies:

# Check for unused packages
npm audit
npm outdated
 
# Remove unused dependencies
npm uninstall unused-package

Unoptimized Images:

# Check image sizes
find dist/assets/images -name "*.jpg" -o -name "*.png" | xargs ls -lh
 
# Use optimized formats (WebP, modern formats)
# Implement lazy loading for images below fold

3. Performance optimization:

// Lazy load images
document.addEventListener('DOMContentLoaded', function() {
  const images = document.querySelectorAll('img[data-src]');
  const imageObserver = new IntersectionObserver((entries, observer) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        const img = entry.target;
        img.src = img.dataset.src;
        img.removeAttribute('data-src');
        imageObserver.unobserve(img);
      }
    });
  });
  
  images.forEach(img => imageObserver.observe(img));
});

Browser Compatibility Issues #

Internet Explorer Support #

Problem: Template doesn't work in older browsers.

Solution: Admindek targets modern browsers. For IE support:

// Add polyfills for older browsers
if (!window.fetch) {
  // Add fetch polyfill
  document.head.appendChild(script);
}
 
// Check for CSS custom property support
if (!CSS.supports('color', 'var(--fake)')) {
  // Fallback for older browsers
  document.documentElement.className += ' no-css-vars';
}

Mobile Browser Issues #

Problem: Issues on iOS Safari or Android Chrome.

Solutions:

1. Check viewport meta tag:

   <meta name="viewport" content="width=device-width, initial-scale=1">

2. Test responsive behavior:

   /* Add iOS-specific fixes */
   @supports (-webkit-touch-callout: none) {
     .ios-fix {
       /* iOS-specific styles */
     }
   }

3. Check touch interactions:

   // Ensure touch events work
   element.addEventListener('touchstart', handleTouch, { passive: true });

Getting Help #

Diagnostic Information to Collect #

When reporting issues, include:

# System information
echo "Node.js: $(node --version)"
echo "NPM: $(npm --version)"
echo "OS: $(uname -a)"
 
# Project information
npm list --depth=0
git status
git log --oneline -3
 
# Error messages (copy full error text)
npm run build 2>&1 | tee build-error.log

Support Channels #

• Email: dashboardpack@gmail.com
• Include: Error messages, system info, steps to reproduce
• Response Time: Usually within 24-48 hours

Prevention Tips #

1. Keep dependencies updated: Regular npm update
2. Use version control: Commit working states frequently
3. Test across browsers: Don't develop in just one browser
4. Monitor console: Check for warnings/errors regularly
5. Backup before changes: Create backups before major modifications

Most issues can be resolved with these solutions. If you encounter a persistent problem not covered here, don't hesitate to contact support with detailed information about your environment and the specific issue.