netlify-cli 23.12.1 breaks Jekyll + Vite-Ruby development setup

[Automaat]

Bug Report: netlify-cli 23.12.1 breaks Jekyll + Vite-Ruby development setup

Description

After upgrading from netlify-cli@23.10.0 to netlify-cli@23.12.1, netlify dev fails to start in a Jekyll project that uses vite-ruby for asset compilation. The CLI incorrectly auto-detects Vite as the primary framework and tries to wait for it on targetPort, causing timeouts.

Environment

• netlify-cli version: 23.12.1 (broken), 23.10.0 (works)
• Node version: 24.11.1
• OS: Ubuntu 22.04 (GitHub Actions), macOS (local)
• Framework: Jekyll 4.4.1 + vite-ruby 5.1.1
• Vite version: 7.2.4

Setup

This project uses:

• Jekyll as the static site generator (runs on port 3000)
• Vite via vite-ruby for asset compilation (runs on port 2036)
• Foreman to orchestrate both processes
• Netlify Dev to proxy the Jekyll server (port 7777 → 3000)

Configuration Files

Procfile:

netlify: npx netlify dev
jekyll: bundle exec jekyll serve --port 3000 --livereload --livereload-port 25729 --config jekyll-dev.yml

netlify.toml:

[dev]
  autoLaunch = false
  port = 7777
  targetPort = 3000

config/vite.json:

{
  "development": {
    "port": 2036
  }
}

Steps to Reproduce

1. Create Jekyll site with vite-ruby gem installed
2. Configure Procfile to start both netlify dev and Jekyll
3. Set config/vite.json with Vite on port 2036
4. Set netlify.toml with targetPort 3000 for Jekyll
5. Run bundle exec foreman start

Expected Behavior (23.10.0)

15:12:54 netlify.1 | ⬥ Starting Vite dev server
15:12:55 netlify.1 | ✔ Vite dev server ready on port 3000
15:12:55 netlify.1 | ✔ Waiting for framework port 3000
15:12:55 netlify.1 |    │   Local dev server ready: http://localhost:7777   │

Netlify Dev correctly waits for Jekyll on port 3000 and starts successfully.

Actual Behavior (23.12.1)

15:12:54 netlify.1 | ⬥ Starting Vite dev server
15:12:55 netlify.1 | ⠋ Waiting for Vite dev server to be ready on port 3000
15:13:10 netlify.1 | ✖ Still waiting for server on port 3000 to be ready. Are you sure this is the correct port for Vite?
15:13:10 netlify.1 | Error: Timed out waiting for port '3000' to be open

Despite Vite running on port 2036 (as configured), netlify-cli 23.12.1 detects it and expects it on targetPort 3000, ignoring that Jekyll is the actual framework serving the site.

Root Cause

Version 23.12.1 introduced more aggressive framework auto-detection that:

1. Detects vite.config.ts presence and assumes Vite is the primary framework
2. Overrides targetPort configuration to wait for Vite instead of Jekyll
3. Ignores that Vite is running on a different port (2036) as configured in config/vite.json

Workarounds Attempted

❌ Setting framework = "#custom" - Requires command parameter, conflicts with Procfile setup

❌ Separating Jekyll to port 4000, Vite to 3000 - Still detects Vite and waits for wrong port

❌ Adding explicit command in netlify.toml - Creates duplicate Jekyll processes with Foreman

✅ Downgrading to netlify-cli@23.10.0 - Works correctly

Proposed Solutions

1. Add framework detection priority: When both Jekyll and Vite are present, prefer Jekyll as the primary framework
2. Respect vite-ruby configuration: Check config/vite.json for actual Vite port before assuming targetPort
3. Document framework override: Clarify how to disable Vite auto-detection when it's used as a build tool, not the primary framework
4. Add ignoreFrameworks option: Allow explicitly ignoring certain framework detectors

Related Issues

• Netlify CLI unexpectedly invokes hugo #791 - ntl dev hangs waiting for port 3000 with Vite
• netlify dev --cwd ./ fails to find vite command in v22.1.7 and above #7528 - netlify dev fails to find vite in v22.1.7+
• waiting for framework port 3000 #4942 - waiting for framework port 3000
• dev server fallback port detection #3818 - dev server fallback port detection

Additional Context

This affects any Jekyll project using vite-ruby, jekyll-vite, or similar asset pipeline integrations where Vite is a build tool, not the primary framework. The 23.10.0 → 23.12.1 upgrade breaks existing working setups without clear migration path.

Full reproduction available at: kumahq/kuma-website#2497