Skip to content

[FEAT] - Expand doctor command with Node.js version check and Tailwind CSS detection #193

Description

@aosmcleod

Description

The doctor command currently only performs 2 checks:

  1. Whether @heroui/react and @heroui/styles are installed
  2. Whether peer dependencies are installed and meet minimum version requirements

There are additional checks that would catch common setup issues before users hit confusing runtime errors.

Proposed additions

1. Node.js version check

The README states Node.js 22+ is required, but the doctor command doesn't verify this. Users on older Node versions get cryptic errors instead of a clear diagnostic.

// Check Node.js version meets minimum requirement
const nodeVersion = process.versions.node;
const [major] = nodeVersion.split('.').map(Number);
if (major < 22) {
  problemRecord.push({
    level: 'error',
    name: 'unsupportedNodeVersion',
    outputFn: () => {
      Logger.log(`Node.js v${nodeVersion} detected, but HeroUI CLI requires Node.js 22 or later.`);
      Logger.log(`Current: v${nodeVersion}`);
      Logger.log(`Required: v22.0.0+`);
      Logger.newLine();
      Logger.log('Upgrade Node.js: https://nodejs.org/');
    }
  });
}

2. Tailwind CSS installation check

The TAILWINDCSS constant already exists in src/constants/required.ts but isn't used in the doctor action. While the peer dependency check might catch this, a dedicated check provides a more helpful error message specific to HeroUI's Tailwind v4 requirement:

// Check Tailwind CSS is installed
if (!allDependenciesKeys.has(TAILWINDCSS)) {
  problemRecord.push({
    level: 'error',
    name: 'missingTailwindCSS',
    outputFn: () => {
      Logger.log('Tailwind CSS is not installed.');
      Logger.log('HeroUI v3 requires Tailwind CSS v4.');
      Logger.newLine();
      Logger.log('Install it with: npm install tailwindcss@latest');
      Logger.log(`See: ${chalk.underline(DOCS_INSTALLED)}`);
    }
  });
}

Why this matters

  • Node version: Users on Node 18/20 (still common LTS versions) will get unhelpful errors. A clear "upgrade Node" message saves debugging time.
  • Tailwind CSS: The generic peer dependency message ("You have not installed the required dependencies") doesn't explain that Tailwind is specifically needed for styling to work, or that v4 is required (not v3).

Current behavior

heroui doctor
# Only checks: packages installed + peer deps met

New behavior

heroui doctor
# Checks: Node version + packages installed + Tailwind CSS + peer deps met

Scope

Small — both checks are straightforward additions to the existing problemRecord pattern in doctor-action.ts. No new dependencies needed.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions