Common Issues - PatternFly 6 Frontend¶

This document covers frequently encountered problems and their solutions when developing with PatternFly 6 React components.

Introduction¶

PatternFly 6 development with Vite can present various challenges ranging from setup issues to component-specific problems. This guide focuses on frontend-specific issues and their solutions.

Setup Guide - Initial setup troubleshooting
External References - Additional troubleshooting resources

Setup Issues¶

Node.js and npm Problems¶

Issue: Command not found errors¶

# Error messages
'node' is not recognized as an internal or external command
'npm' is not recognized as an internal or external command

Solutions:

Verify Installation:

# Check if Node.js is installed
node --version
npm --version

Reinstall Node.js:
Download from https://nodejs.org/
Choose LTS version for stability
Restart terminal after installation
PATH Configuration:

# Windows: Add to PATH environment variable
C:\Program Files\nodejs\

# macOS/Linux: Add to shell profile
export PATH="/usr/local/bin/node:$PATH"

Issue: npm permission errors¶

# Error message
EACCES: permission denied, access '/usr/local/lib/node_modules'

Solutions:

Use nvm (Recommended):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node.js
nvm install node
nvm use node

Fix npm permissions:

# Create global directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH
export PATH=~/.npm-global/bin:$PATH

Project Setup Issues¶

Issue: Git clone failures¶

# Error message
fatal: repository 'https://github.com/patternfly/patternfly-react-seed' not found

Solutions:

Check Network Connection: Verify internet connectivity

Use HTTPS instead of SSH:

git clone https://github.com/patternfly/patternfly-react-seed

Check Repository URL: Verify the repository exists and URL is correct

Issue: npm install failures¶

# Error messages
npm ERR! network request failed
npm ERR! peer dep missing

Solutions:

Clear npm cache:

npm cache clean --force

Delete node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

Check npm registry:

npm config get registry
# Should return: https://registry.npmjs.org/

Install with legacy peer deps:
```
npm install --legacy-peer-deps
```

Development Server Issues¶

Issue: Port already in use¶

# Error message
Error: listen EADDRINUSE: address already in use :::3000

Solutions:

Find and kill process:

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# macOS/Linux
lsof -ti:3000 | xargs kill -9

Use different port:

// vite.config.ts
server: {
  port: 3001,
}

Issue: Development server not starting¶

# Error message
Error: Cannot find module 'vite'
Error: Failed to resolve plugin

Solutions:

Reinstall frontend dependencies:

cd frontend
rm -rf node_modules package-lock.json
npm install

Check Vite configuration:

// Verify frontend/vite.config.ts exists

Clear Vite cache:

rm -rf frontend/node_modules/.vite
npm run dev:frontend

Import and Module Issues¶

PatternFly Component Import Errors¶

Issue: Module not found errors¶

# Error message
Module not found: Can't resolve '@patternfly/react-core'

Solutions:

Install PatternFly packages:

npm install @patternfly/react-core @patternfly/react-table @patternfly/react-icons

Check import syntax:

// Correct imports
import { Button, Card } from '@patternfly/react-core'
import { Table, Thead, Tbody } from '@patternfly/react-table'
import { UserIcon } from '@patternfly/react-icons'

Verify package.json dependencies:

{
  "dependencies": {
    "@patternfly/react-core": "^6.x.x",
    "@patternfly/react-table": "^6.x.x",
    "@patternfly/react-icons": "^6.x.x"
  }
}

Issue: Charts module not found¶

# Error message
Module not found: Can't resolve '@patternfly/react-charts/victory'

Solutions:

Install charts dependencies:

npm install @patternfly/react-charts victory

Use correct import paths:

// Correct chart imports
import { ChartDonut, ChartLine } from '@patternfly/react-charts/victory'

Clear cache and reinstall:

rm -rf node_modules package-lock.json
npm install

Issue: Chatbot module not found¶

# Error message
Module not found: Can't resolve '@patternfly/chatbot/dist/dynamic/Chatbot'

Solutions:

Install chatbot package:

npm install @patternfly/chatbot

Import CSS:

import '@patternfly/chatbot/dist/css/main.css'

Use correct import paths:

import { Chatbot } from '@patternfly/chatbot/dist/dynamic/Chatbot'

Styling Issues¶

CSS and Class Problems¶

Issue: PatternFly styles not applied¶

# Symptoms: Components appear unstyled or with default browser styles

Solutions:

Import PatternFly CSS:

// In your main App.js or index.js
import '@patternfly/react-core/dist/styles/base.css'

Check CSS import order:

// PatternFly CSS should be imported before custom CSS
import '@patternfly/react-core/dist/styles/base.css'
import './custom-styles.css'

Verify webpack CSS handling:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
}

Issue: Wrong PatternFly version classes¶

// Problem: Using old class names
<div className="pf-c-button">  // v4 class
<div className="pf-v5-c-button">  // v5 class

Solutions:

Use PatternFly v6 classes:

// Correct v6 classes
<div className="pf-v6-c-button">
<div className="pf-v6-u-margin-md">

Update class references:

# Find and replace old classes
grep -r "pf-c-" src/
grep -r "pf-v5-" src/

Use PatternFly components instead:

// Instead of manual classes, use components
import { Button } from '@patternfly/react-core'
;<Button variant="primary">Click me</Button>

Layout and Responsive Issues¶

Issue: Components not responsive¶

// Problem: Fixed widths and heights
<div style={{ width: '800px', height: '600px' }}>

Solutions:

Use PatternFly responsive utilities:

<div className="pf-v6-u-width-100 pf-v6-u-height-auto">

Implement responsive patterns:

<div className="pf-v6-l-grid pf-v6-m-gutter">
  <div className="pf-v6-l-grid__item pf-v6-m-12-col pf-v6-m-6-col-on-md">Content</div>
</div>

Use container-based sizing:

const [dimensions, setDimensions] = useState({ width: 0, height: 0 })

useEffect(() => {
  const updateDimensions = () => {
    if (containerRef.current) {
      const { width, height } = containerRef.current.getBoundingClientRect()
      setDimensions({ width, height })
    }
  }

  updateDimensions()
  window.addEventListener('resize', updateDimensions)
  return () => window.removeEventListener('resize', updateDimensions)
}, [])

PatternFly 6 Deprecated Components¶

Completely Deprecated in v6¶

These components are no longer supported and require migration:

Old Select Component¶

// ❌ Deprecated
import { Select, SelectOption } from '@patternfly/react-core/deprecated'

// ✅ Use new Select
import { Select, SelectOption } from '@patternfly/react-core'

// ❌ Deprecated
import { Dropdown, DropdownToggle } from '@patternfly/react-core/deprecated'

// ✅ Use new Dropdown
import { Dropdown, DropdownList, DropdownItem } from '@patternfly/react-core'

Old Wizard Component¶

// ❌ Deprecated
import { Wizard } from '@patternfly/react-core/deprecated'

// ✅ Use new Wizard
import { Wizard, WizardStep } from '@patternfly/react-core'

Old Table Component¶

// ❌ Deprecated non-composable table

// ✅ Use composable table
import { Table, Thead, Tbody, Tr, Th, Td } from '@patternfly/react-table'

Component API Changes¶

Button isDisabled → disabled¶

// ❌ Old
<Button isDisabled={true}>Click</Button>

// ✅ New
<Button disabled={true}>Click</Button>

Text → Content¶

// ❌ Old
import { Text } from '@patternfly/react-core'
;<Text component="h1">Title</Text>

// ✅ New
import { Content } from '@patternfly/react-core'
;<Content component="h1">Title</Content>

PageHeader Removed¶

// ❌ Old
<PageHeader title="My Page" />

// ✅ New - Use PageSection with Title
<PageSection>
  <Title headingLevel="h1">My Page</Title>
</PageSection>

Component-Specific Issues¶

// Problem: Dropdown appears cut off in scrollable containers

Solutions:

Use appendTo prop:

<Dropdown
  popperProps={{
    appendTo: () => document.body,
    position: 'right',
    enableFlip: true
  }}
>

Configure positioning:

<Dropdown
  popperProps={{
    position: 'right',
    enableFlip: true,
    preventOverflow: true
  }}
>

Table Performance Issues¶

Issue: Slow rendering with large datasets¶

// Problem: Table becomes unresponsive with 1000+ rows

Solutions:

Implement pagination:

import { Pagination } from '@patternfly/react-core'

const [page, setPage] = useState(1)
const [perPage, setPerPage] = useState(20)
const paginatedData = data.slice((page - 1) * perPage, page * perPage)

Use virtualization:

import { DndProvider, useDrag, useDrop } from 'react-dnd';
import { HTML5Backend } from 'react-dnd-html5-backend';
import { Table, Thead, Tbody, Tr, Th, Td } from '@patternfly/react-table';

const DraggableRow = ({ id, text, index, moveRow }) => {
// ... existing code ...

Optimize re-renders:

const MemoizedRow = React.memo(({ item }) => (
  <Tr>
    <Td>{item.name}</Td>
    <Td>{item.email}</Td>
  </Tr>
))

Vite-Specific Issues¶

HMR (Hot Module Replacement) Not Working¶

Issue: Changes not reflecting in browser¶

# Symptoms: File saves don't trigger browser updates

Solutions:

Clear Vite cache:

rm -rf frontend/node_modules/.vite

Check Vite config:

// vite.config.ts
server: {
  hmr: {
    overlay: true
  }
}

Use polling for WSL/Docker:

server: {
  watch: {
    usePolling: true
  }
}

API Integration Issues¶

Issue: API calls failing¶

# Error: 404 on /api/* routes or CORS errors

Solutions:

Check proxy configuration:

// vite.config.ts
proxy: {
  '/api': {
    target: 'http://localhost:8081',
    changeOrigin: true,
  }
}

Use environment variables:

// Use VITE_API_URL for API calls
const apiUrl = import.meta.env.VITE_API_URL || 'http://localhost:8081'

Frontend Build Issues¶

Build Failures¶

Issue: Vite build process fails¶

# Error message
Error: [vite]: Rollup failed to resolve import

Solutions:

Check for TypeScript errors:

cd frontend && npx tsc --noEmit

Verify all imports:

npm run lint

Clear build output:

rm -rf frontend/dist
npm run build:frontend

Issue: Bundle size too large¶

# Warning: Bundle size exceeds recommended limit

Solutions:

Analyze Vite bundle:

# Build with analysis
cd frontend && npx vite build --mode analyze

# Or use rollup-plugin-visualizer
npm install --save-dev rollup-plugin-visualizer

Implement code splitting:

// Vite handles dynamic imports automatically
const LazyComponent = React.lazy(() => import('./HeavyComponent'))

;<Suspense fallback={<Spinner />}>
  <LazyComponent />
</Suspense>

Optimize imports:

// vite.config.ts
build: {
  rollupOptions: {
    output: {
      manualChunks: {
        'react-vendor': ['react', 'react-dom'],
        'patternfly-vendor': ['@patternfly/react-core']
      }
    }
  }
}

Browser Compatibility Issues¶

Cross-Browser Problems¶

Issue: Components not working in specific browsers¶

# Symptoms: Features work in Chrome but not Safari/Firefox

Solutions:

Check Vite browser targets:

// vite.config.ts
export default defineConfig({
  build: {
    target: 'es2015',
  },
})

Add polyfills if needed:

npm install @vitejs/plugin-legacy

// vite.config.ts
import legacy from '@vitejs/plugin-legacy'

plugins: [
  legacy({
    targets: ['defaults', 'not IE 11'],
  }),
]

Test across browsers:
Use browser dev tools
Test on actual devices
Use Playwright for automated testing

Frontend-Specific Issues¶

Module Resolution¶

Issue: PatternFly modules not found¶

# Error: Cannot find module '@patternfly/react-core'

Solutions:

Install PatternFly packages:

cd frontend
npm install @patternfly/react-core @patternfly/react-table @patternfly/react-icons

Verify package versions:

npm list @patternfly/react-core

Clean install if needed:

cd frontend
rm -rf node_modules package-lock.json
npm install

Debugging Strategies¶

Frontend Debugging Approach¶

Browser Console: Check for React and PatternFly warnings
React DevTools: Inspect component props and state
Network Tab: Monitor API calls and asset loading
TypeScript: Run npm run type-check for type errors
Documentation: Reference this pf6-guide for best practices

Debug Tools¶

React DevTools: Inspect component state and props
Browser DevTools: Network, console, and element inspection
Vite Inspector: Press h in terminal for Vite shortcuts
Playwright UI: Run npm run test:e2e:ui for visual debugging
Vitest UI: Run npm run test:ui for test debugging

Getting Help¶

GitHub Issues: Search and create issues with minimal reproduction
Stack Overflow: Use patternfly tag for questions
Community Slack: Real-time help from community
Documentation: Always check latest official documentation

Prevention Strategies¶

Best Practices¶

Keep Dependencies Updated: Update PatternFly 6 packages together
Use pf6-guide: Follow this guide as the source of truth for PatternFly practices
Test Both Themes: Always test in light and dark themes
Use Rem Units: Convert px to rem (divide by 16) for breakpoints
Follow Token System: Use semantic design tokens, not hardcoded values
Run Codemods: Use migration tools when upgrading

Code Quality¶

Type Safety: Use TypeScript when possible
Testing: Write unit tests for components
Code Review: Review changes for PatternFly compliance
Performance Monitoring: Track bundle size and performance metrics

Remember: When encountering issues, always check the official PatternFly documentation first, then search GitHub issues for similar problems. Provide specific error messages, code snippets, and version information when seeking help.

Common Issues - PatternFly 6 Frontend¶

Introduction¶

Related Files¶

Setup Issues¶

Node.js and npm Problems¶

Issue: Command not found errors¶

Issue: npm permission errors¶

Project Setup Issues¶

Issue: Git clone failures¶

Issue: npm install failures¶

Development Server Issues¶

Issue: Port already in use¶

Issue: Development server not starting¶

Import and Module Issues¶

PatternFly Component Import Errors¶

Issue: Module not found errors¶

Issue: Charts module not found¶

Issue: Chatbot module not found¶

Styling Issues¶

CSS and Class Problems¶

Issue: PatternFly styles not applied¶

Issue: Wrong PatternFly version classes¶

Layout and Responsive Issues¶

Issue: Components not responsive¶

PatternFly 6 Deprecated Components¶

Completely Deprecated in v6¶

Old Select Component¶

Old Dropdown Component¶

Old Wizard Component¶

Old Table Component¶

Component API Changes¶

Button isDisabled → disabled¶

Text → Content¶

PageHeader Removed¶

Component-Specific Issues¶

Dropdown Clipping Issues¶

Issue: Dropdown menu gets clipped¶

Table Performance Issues¶

Issue: Slow rendering with large datasets¶

Vite-Specific Issues¶

HMR (Hot Module Replacement) Not Working¶

Issue: Changes not reflecting in browser¶

API Integration Issues¶

Issue: API calls failing¶

Frontend Build Issues¶

Build Failures¶

Issue: Vite build process fails¶

Issue: Bundle size too large¶

Browser Compatibility Issues¶

Cross-Browser Problems¶

Issue: Components not working in specific browsers¶

Frontend-Specific Issues¶

Module Resolution¶

Issue: PatternFly modules not found¶

Debugging Strategies¶

Frontend Debugging Approach¶

Debug Tools¶

Getting Help¶

Prevention Strategies¶

Best Practices¶

Code Quality¶