Introduction

When I decided to migrate the Nurohive website from traditional HTML/CSS to Next.js, I never imagined I would fall into such a deep environment setup hell. This article is a candid record of the numerous errors I faced and the process of resolving them. I hope it helps anyone facing similar issues.

Environment and Goal

• Next.js Version: (Specify your Next.js version here, found from npx create-next-app output or package.json)
• Node.js Version: (Specify your Node.js version, from node -v result)
• npm/Yarn Version: (Specify your npm/Yarn version, from npm -v or yarn -v result)
• Goal: Correctly compile existing SCSS with Next.js App Router and display the site.

The Gateway to Hell: Next.js Project Creation Pitfalls and Choices

My struggle began when I executed the npx create-next-app command and initially answered Yes to the ESLint and Tailwind CSS options.

The Command Executed and Answers Provided (Initial Attempt)

npx create-next-app nurohive-next --typescript --eslint --tailwind --src-dir --app

Answers to prompts:

• Would you like to use ESLint? → Yes
• Would you like to use Tailwind CSS? → Yes
• Would you like to use Turbopack for next dev? → No
• Would you like to customize the import alias (@/* by default)? → No

The Root Cause of the Problem

Introducing ESLint and Tailwind CSS at the initial stage led to the generation of their respective configuration files (eslint.config.mjs, tailwind.config.ts, postcss.config.mjs, etc.). These configurations subsequently caused complex conflicts with Sass during the build process. The primary challenge was the discrepancy between Tailwind CSS v4's new import methods and the Sass compiler's recognition of these directives.

Ordeal 1: SCSS Integration and Unknown Tailwind CSS @rules

When attempting to integrate the existing style.scss into Next.js as global styles in src/app/styles/global-styles.scss, I encountered numerous errors. The main issue was that the Sass compiler did not recognize Tailwind CSS's @theme and @tailwind directives.

Example Errors Encountered

Unknown at rule @theme
Unknown at rule @tailwind

Trial and Error Process

• Attempted to delete the @theme inline { ... } block.
• Changed @import "tailwindcss"; to @tailwind base; @tailwind components; @tailwind utilities;.
• Subsequently, warnings began appearing about @tailwind base; and @tailwind components; being deprecated in Tailwind CSS v4, leading to a final change to @import "tailwindcss/preflight"; and @tailwind utilities;. However, the Unknown at rule @tailwind errors persisted.
• This suggested a fundamental issue with how the Sass compiler processed Tailwind CSS directives, potentially due to the processing order within Next.js's build pipeline or version incompatibilities.

Ordeal 2: Tailwind CSS v4 Wall and npx Issues

As Unknown at rule @tailwind errors continued, I sought to solve it by running npx tailwindcss init -p to reinitialize Tailwind CSS settings. However, a new set of problems arose.

Example Error Encountered

npm error could not determine executable to run

Trial and Error Process

• Attempted reinstallation of tailwindcss package.
• Performed complete deletion and reinstallation of node_modules and package-lock.json.
• Tried directly executing ./node_modules/.bin/tailwindcss init -p, but encountered a "file or directory not found" error.
• It was inferred that npx or npm was unable to correctly resolve the executable path of the installed package, or the tailwindcss@next (v4) package structure was too specific for direct execution in my environment.

Ordeal 3: Git Repository Corruption and Push Rejection

In my attempts to resolve the preceding errors by recreating the Next.js project and cleaning up Git-related files, the Git repository itself fell into an abnormal state.

Example Errors Encountered

error: src refspec feat/setup-nextjs-blog does not match any
error: failed to push some refs to 'https://github.com/auroraund/nurohive.git'

This indicated a paradoxical state where local commits existed, yet pushes were rejected.

The Root Cause

The fundamental cause of this issue was making commits inside the nurohive-next subdirectory after it was created within the main nurohive Git repository.

This action likely created a hidden, nested .git directory within nurohive-next. When I subsequently tried to delete this nested .git directory, it corrupted the main nurohive repository's internal reference information, leading to a severe internal inconsistency that prevented normal Git operations, including pushing changes. Even git push -u and --force-with-lease failed, signifying a deep-seated issue with Git's internal state.

The Great Escape: Clean Environment Reconstruction and Correct SCSS Integration!

After numerous errors and moments of despair, I finally resorted to a "complete reset and reconstruction" strategy. This proved to be the only way out of the setup hell.

1. Completely delete the existing nurohive directory.

   rm -rf /home/auroraund/nurohive
   

2. Re-clone the clean repository from GitHub.

   git clone https://github.com/auroraund/nurohive.git
   

3. Create a new, clean branch for Next.js integration. (e.g., feat/setup-nextjs-blog-final)

   cd nurohive
   git checkout -b feat/setup-nextjs-blog-final
   

4. Recreate the simplest Next.js project. (No Tailwind, no ESLint)

   npx create-next-app nurohive-next --typescript --eslint=false --tailwind=false --src-dir --app
   

5. Install only the sass package.

   cd nurohive-next
   npm install -D sass
   cd ..
   

6. Copy existing image files to nurohive-next/public/images/.

   cp -r images/ nurohive-next/public/
   

7. Correctly integrate destyle.css and style.scss into nurohive-next/src/app/styles/global-styles.scss.
   • Delete the default nurohive-next/src/app/globals.css.
   • Open nurohive-next/src/app/styles/global-styles.scss and paste the content of destyle.css at the very top, followed by the content of style.scss (preserving SCSS nesting).
8. Modify nurohive-next/src/app/layout.tsx to correctly import global-styles.scss.

   // src/app/layout.tsx
   import './styles/global-styles.scss';
   // ...
   <html lang="en"> {/* lang="en" ensures consistency */}
   

9. Modify nurohive-next/src/app/page.tsx to integrate index.html content as JSX.
   • Convert class to className.
   • Self-closing <img> tags (<img ... />).
   • Correct image paths to src="/images/...".
   • Adjust internal link hrefs to Next.js paths (e.g., /projects, /about).

Victory!

By following these rigorous steps, Nurohive's homepage finally rendered correctly on Next.js. All command-line errors were resolved, and a clean development environment was established.

(Describe the feeling of screaming "KITA!" and the joy of seeing the site displayed in the browser. You can embed screenshots here later!)

Lessons Learned

From this experience, I gained several crucial lessons:

1. "Simplicity is Best": When learning a new framework, always start with the minimal configuration. Add optional features later.
2. Deep Dive into Error Messages and Isolate Causes: Go beyond superficial errors to find root causes. This is especially critical for tools like Git with complex internal states.
3. Re-verify Git Fundamentals: Mistakes in basic operations like committing from the correct directory or understanding branch tracking can lead to severe issues.
4. Consult Official Documentation and Latest Information: Major updates, like Tailwind CSS v4, can introduce significant changes in setup.
5. Perseverance: No matter how many errors appear, tackling them one by one leads to success.
6. Utilize Community and AI: Don't hesitate to ask questions when stuck.

Future Outlook

The Next.js migration for Nurohive is just the beginning. The next steps involve migrating the remaining pages, implementing full blog functionality, and ultimately integrating the Whensday service. I hope this development log helps others on a similar journey.