stackshifter

StackShifter.

A powerful CLI tool to effortlessly migrate your React applications to Next.js with automatic file restructuring, CSS Modules conversion, and routing transformation.

Features

• Automatic File Restructuring: Converts React project structure to Next.js 13+ App Directory
• CSS Modules Migration: Automatically converts CSS to CSS Modules with updated imports
• Smart Routing: Transforms React Router routes to Next.js pages with nested route support
• Component Organization: Preserves component hierarchy and relationships
• Import Path Correction: Fixes all import paths to match Next.js structure
• "use client" Directives: Automatically adds client directives for interactive components
• Public Asset Migration: Copies and organizes static assets
• Two Migration Modes: Manual (shiftto) or automatic (migrate) workflows

🚀 Quick Start

Installation

Option 1: Clone from GitHub (Development)

git clone https://github.com/yourusername/stackshifter.git
cd stackshifter
npm install
npm link  # Makes stackshifter command available globally

Option 2: Install from npm (Coming Soon)

npm install -g stackshifter

Usage

StackShifter provides two powerful commands for different migration workflows:

1. shiftto - Manual Migration

Creates a migration-output folder that you manually copy to your Next.js project.

Migrate React to Next.js (Pages Directory)

stackshifter shiftto nextjs -i ./my-react-app

Convert JSX to TSX

stackshifter shiftto tsx -i ./component.jsx

2. migrate - Automatic Migration

Creates a complete Next.js 13+ app with your migrated code automatically integrated.

stackshifter migrate -s ./my-react-app -t ./output-directory -n my-nextjs-app

Options:

• -s, --source <path>: React app source directory (default: current directory)
• -t, --target <path>: Directory where Next.js app will be created (required)
• -n, --name <name>: Name of the Next.js app (required)
• --no-start: Don't automatically start the development server

How It Works

Migration Pipeline (8 Steps)

• Copy Public Assets
  Migrates public/ folder contents to maintain static assets

• Handle Styles
  Converts CSS files to CSS Modules (.module.css) with automatic class name updates

• Process Source Files
  Copies and processes src/pages/ and src/components/ with nested directory support

• Normalize Pages
  Converts React Router structure to Next.js pages with dynamic routes support

• Fix Class Names
  Updates JSX to use CSS Modules syntax (className={styles.className})

• JSX Transformations

  • Removes React Router imports (react-router-dom)
  • Converts <Link to="..."> to <Link href="...">
  • Removes <BrowserRouter>, <Routes>, <Route> wrappers
  • Adds Next.js Link imports

• Correct Import Paths
  Updates all import statements to match new file structure

• Add "use client" Directives
  Automatically detects and adds client directives for components using:

  • React hooks (useState, useEffect, etc.)
  • Event handlers (onClick, onChange, etc.)
  • Browser APIs (window, localStorage, etc.)

Project Structure Requirements

Input (React App)

my-react-app/
├── public/
│   ├── favicon.ico
│   └── images/
├── src/
│   ├── components/
│   │   ├── Header.jsx
│   │   └── Footer/
│   │       └── Footer.jsx
│   ├── pages/
│   │   ├── index.jsx        # Homepage
│   │   ├── about.jsx        # About page
│   │   └── blog/
│   │       ├── index.jsx    # Blog homepage
│   │       └── [slug].jsx   # Dynamic blog post
│   ├── styles/
│   │   ├── globals.css
│   │   └── components.css
│   └── App.jsx
└── package.json

Output (Next.js 13+ App)

my-nextjs-app/
├── public/              # ← Copied from React app
├── styles/              # ← CSS Modules (.module.css)
├── src/
│   ├── app/             # ← Next.js 13+ App Directory
│   │   ├── page.js      # ← From pages/index.jsx
│   │   ├── layout.js    # ← Auto-generated
│   │   ├── about/
│   │   │   └── page.js  # ← From pages/about.jsx
│   │   └── blog/
│   │       ├── page.js  # ← From pages/blog/index.jsx
│   │       └── [slug]/
│   │           └── page.js  # ← From pages/blog/[slug].jsx
│   └── components/      # ← Processed components with CSS Modules
└── package.json

Advanced Features

Nested Pages Support

StackShifter automatically handles complex nested page structures:

// Input: src/pages/dashboard/analytics/reports.jsx
// Output: src/app/dashboard/analytics/reports/page.js

Dynamic Routes

Supports all Next.js dynamic routing patterns:

• [id].jsx → [id]/page.js (Single dynamic segment)
• [...slug].jsx → [...slug]/page.js (Catch-all routes)
• [[...slug]].jsx → [[...slug]]/page.js (Optional catch-all)

CSS Modules Integration

Automatically converts and updates CSS usage:

// Before
import './Button.css';
<button className="primary-btn">Click me</button>

// After
import styles from '../../styles/Button.module.css';
<button className={styles.primaryBtn}>Click me</button>

What's Included & Future Enhancements

StackShifter focuses on the core migration challenges that matter most - file structure, routing, styling, and component compatibility. Here's what we handle automatically and what you might need to fine-tune:

Fully Automated

• Complete file restructuring and routing migration
• CSS Modules conversion with import updates
• Component hierarchy preservation
• "use client" directive placement
• Public asset organization

May Need Manual Review (Usually Quick Fixes)

• API Routes: We migrate your frontend perfectly! For backend endpoints, simply create new files in app/api/ - Next.js makes this super easy
• Advanced Next.js 13+ Features: Your migrated app works immediately. You can gradually adopt Server Components, Streaming, and other modern features at your own pace
• Custom Build Config: Standard Webpack configs usually aren't needed in Next.js - the framework handles most optimizations automatically
• Complex State Management: Libraries like Redux/Zustand typically work out-of-the-box, but you may want to optimize for Next.js patterns
• Test Files: Your existing tests often work with minimal changes - just update import paths if needed

Pro Tip

Most "limitations" are actually opportunities to modernize! Next.js 13+ provides better alternatives to many custom configurations, and our migration gives you a solid foundation to build upon.

Bottom Line: StackShifter handles the heavy lifting (90% of migration work), leaving you with minor adjustments that are often improvements to your codebase!

Examples

Basic React App Migration

# Create migration output folder
stackshifter shiftto nextjs -i ./my-react-app

# Or create complete Next.js app
stackshifter migrate -s ./my-react-app -t ./projects -n awesome-nextjs-app

Convert Single JSX to TSX

stackshifter shiftto tsx -i ./components/Button.jsx
# Creates: ./components/Button.tsx

Complex Project with Nested Pages

stackshifter migrate \
  -s ./complex-react-app \
  -t ./output \
  -n migrated-app \
  --no-start

Testing Your Migration

After migration, verify these key areas:

• Routing: Test all page navigation
• Styling: Verify CSS Modules are working
• Components: Check interactive features work
• Images/Assets: Confirm static assets load correctly
• Console: Check for any client/server component errors

Development Setup

git clone https://github.com/Aditya0o7/stackshifter.git
cd stackshifter
npm install
npm link

Running Tests

npm test

Built with ❤️ using:

• jscodeshift for code transformations
• globby for file pattern matching
• fs-extra for file operations

📄 License

MIT © Aditya Sharma, Abhinav Verma

This project is licensed under the MIT License - see the LICENSE file for details

Happy migrating!