Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#7,810 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
45/100
Loại issue
Lỗi
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
jekyll, typescript, vite
Lĩnh vực
cli, tooling

Hướng nghiên cứu

Tái hiện lỗi với Procfile, netlify.toml và config/vite.json được mô tả trong issue, đồng thời so sánh netlify-cli 23.10.0 với 23.12.1. Theo dõi cơ chế tự động phát hiện framework của CLI và hành vi chờ cổng; được xem là hoàn tất khi máy chủ Jekyll trên targetPort 3000 khởi động thành công mà Vite không bị coi là framework chính.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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

Description

After upgrading from [email protected] to [email protected], 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 [email protected] - 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
  • #791 - ntl dev hangs waiting for port 3000 with Vite
  • #7528 - netlify dev fails to find vite in v22.1.7+
  • #4942 - waiting for framework port 3000
  • #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

Ngôn ngữ chính
TypeScript
Star
1.9k
Fork
481
Merge trung bình
1 ngày 11 giờ
Pull request đã merge (30 ngày)
74

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của netlify/cli

Tất cả issue của netlify/cli

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.