How to Use Raycast 2.0 to Speed Up Development Workflow with Next.js 16 Shortcuts

// Import Raycast API types for type safety
import { Action, ActionPanel, Icon, List, showToast, ToastStyle } from '@raycast/api';
import { execa } from 'execa';
import fs from 'fs-extra';
import path from 'path';
import os from 'os';

// Type definition for a single Next.js 16 shortcut configuration
interface NextShortcutConfig {
  id: string;
  title: string;
  description: string;
  icon: Icon;
  command: string;
  args: string[];
  needsProjectContext: boolean;
  errorHandler?: (error: Error) => Promise;
}

// Registry of all 16 Next.js 16 shortcuts for Raycast 2.0
export const NEXT_16_SHORTCUTS: NextShortcutConfig[] = [
  {
    id: 'scaffold-project',
    title: 'Scaffold Next.js 16 Project',
    description: 'Create a new Next.js 16 project with TypeScript, Tailwind, and App Router preconfigured',
    icon: Icon.Plus,
    command: 'npx',
    args: ['create-next-app@16', '--typescript', '--tailwind', '--eslint', '--app', '--src-dir', '--import-alias', '@/*', '--use-npm'],
    needsProjectContext: false,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Scaffold Failed', `Project creation failed: ${error.message}`);
    }
  },
  {
    id: 'start-dev-server',
    title: 'Start Next.js 16 Dev Server',
    description: 'Launch Next.js 16 development server on port 3000 with TurboPack enabled',
    icon: Icon.Play,
    command: 'npm',
    args: ['run', 'dev', '--', '--turbo'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Dev Server Failed', `Server start failed: ${error.message}`);
    }
  },
  {
    id: 'build-production',
    title: 'Build Next.js 16 Production Bundle',
    description: 'Generate optimized production build with static site generation and incremental static regeneration',
    icon: Icon.Box,
    command: 'npm',
    args: ['run', 'build'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Build Failed', `Production build failed: ${error.message}`);
    }
  },
  {
    id: 'start-prod-server',
    title: 'Start Next.js 16 Production Server',
    description: 'Launch production server from .next build output',
    icon: Icon.Server,
    command: 'npm',
    args: ['run', 'start'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Prod Server Failed', `Production server start failed: ${error.message}`);
    }
  },
  {
    id: 'run-tests',
    title: 'Run Next.js 16 Test Suite',
    description: 'Execute Jest test suite with Next.js 16 test utils',
    icon: Icon.Checkmark,
    command: 'npm',
    args: ['run', 'test'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Tests Failed', `Test execution failed: ${error.message}`);
    }
  },
  {
    id: 'lint-project',
    title: 'Lint Next.js 16 Project',
    description: 'Run ESLint and TypeScript type checking across project',
    icon: Icon.Warning,
    command: 'npm',
    args: ['run', 'lint'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Lint Failed', `Linting failed: ${error.message}`);
    }
  },
  {
    id: 'format-code',
    title: 'Format Next.js 16 Codebase',
    description: 'Run Prettier and organize imports across project files',
    icon: Icon.Document,
    command: 'npm',
    args: ['run', 'format'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Format Failed', `Code formatting failed: ${error.message}`);
    }
  },
  {
    id: 'deploy-vercel',
    title: 'Deploy Next.js 16 to Vercel',
    description: 'Deploy current project to Vercel production environment',
    icon: Icon.Upload,
    command: 'npx',
    args: ['vercel', '--prod'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Deploy Failed', `Vercel deployment failed: ${error.message}`);
    }
  },
  {
    id: 'analyze-bundle',
    title: 'Analyze Next.js 16 Bundle Size',
    description: 'Generate interactive bundle size analysis report with @next/bundle-analyzer',
    icon: Icon.ChartBar,
    command: 'npm',
    args: ['run', 'analyze'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Analysis Failed', `Bundle analysis failed: ${error.message}`);
    }
  },
  {
    id: 'clear-cache',
    title: 'Clear Next.js 16 Cache',
    description: 'Delete .next build cache, node_modules/.cache, and TurboPack cache',
    icon: Icon.Trash,
    command: 'rm',
    args: ['-rf', '.next', 'node_modules/.cache', '.turbo'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Cache Clear Failed', `Cache deletion failed: ${error.message}`);
    }
  },
  {
    id: 'open-docs',
    title: 'Open Next.js 16 Docs',
    description: 'Launch Next.js 16 official documentation in default browser',
    icon: Icon.Book,
    command: 'open',
    args: ['https://nextjs.org/docs/16'],
    needsProjectContext: false,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Docs Open Failed', `Failed to open docs: ${error.message}`);
    }
  },
  {
    id: 'debug-server',
    title: 'Debug Next.js 16 Dev Server',
    description: 'Launch dev server with Node.js inspector enabled on port 9229',
    icon: Icon.Bug,
    command: 'node',
    args: ['--inspect', 'node_modules/.bin/next', 'dev'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Debug Failed', `Debug server start failed: ${error.message}`);
    }
  },
  {
    id: 'generate-component',
    title: 'Generate Next.js 16 Component',
    description: 'Scaffold a new React Server Component with TypeScript and CSS Modules',
    icon: Icon.Code,
    command: 'npx',
    args: ['generate-next-component', '--typescript', '--css-modules'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Component Gen Failed', `Component generation failed: ${error.message}`);
    }
  },
  {
    id: 'check-updates',
    title: 'Check Next.js 16 Dependency Updates',
    description: 'Check for outdated Next.js 16 and related dependencies',
    icon: Icon.Download,
    command: 'npm',
    args: ['outdated', 'next', 'react', 'react-dom'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Update Check Failed', `Dependency check failed: ${error.message}`);
    }
  },
  {
    id: 'run-e2e-tests',
    title: 'Run Next.js 16 E2E Tests',
    description: 'Execute Playwright E2E test suite against local dev server',
    icon: Icon.Eye,
    command: 'npm',
    args: ['run', 'test:e2e'],
    needsProjectContext: true,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'E2E Tests Failed', `E2E test execution failed: ${error.message}`);
    }
  },
  {
    id: 'kill-port',
    title: 'Kill Process on Port 3000',
    description: 'Terminate any process running on Next.js default port 3000',
    icon: Icon.Stop,
    command: 'lsof',
    args: ['-ti:3000', '-sTCP:LISTEN', '|', 'xargs', 'kill', '-9'],
    needsProjectContext: false,
    errorHandler: async (error) => {
      await showToast(ToastStyle.Failure, 'Port Kill Failed', `Failed to kill port 3000 process: ${error.message}`);
    }
  }
];

// Validate that all 16 shortcuts are registered
if (NEXT_16_SHORTCUTS.length !== 16) {
  throw new Error(`Expected 16 shortcuts, found ${NEXT_16_SHORTCUTS.length}. Update registry.`);
}

// Helper to check if current working directory is a Next.js project
export async function isNextProject(projectPath: string): Promise {
  try {
    const packageJsonPath = path.join(projectPath, 'package.json');
    if (!await fs.pathExists(packageJsonPath)) return false;
    const packageJson = await fs.readJson(packageJsonPath);
    return packageJson.dependencies?.next?.startsWith('16') || packageJson.devDependencies?.next?.startsWith('16');
  } catch (error) {
    console.error('Project validation failed:', error);
    return false;
  }
}

// Import required dependencies for shortcut execution
import { showToast, ToastStyle, getPreferenceValues, open } from '@raycast/api';
import { execa } from 'execa';
import path from 'path';
import os from 'os';
import { NEXT_16_SHORTCUTS, isNextProject } from './shortcut-registry';
import fs from 'fs-extra';

// Define Raycast preference types for user configuration
interface Preferences {
  defaultProjectPath: string;
  vercelToken: string;
  bundleAnalyzerPort: number;
}

// Get user preferences with defaults
const preferences = getPreferenceValues({
  defaultProjectPath: path.join(os.homedir(), 'projects'),
  vercelToken: '',
  bundleAnalyzerPort: 8888
});

// Main handler to execute a selected Next.js 16 shortcut
export async function executeShortcut(shortcutId: string): Promise {
  // Find the shortcut configuration by ID
  const shortcut = NEXT_16_SHORTCUTS.find(s => s.id === shortcutId);
  if (!shortcut) {
    await showToast(ToastStyle.Failure, 'Shortcut Not Found', `No shortcut with ID: ${shortcutId}`);
    return;
  }

  // Determine project path: use current working directory or default preference
  let projectPath = process.cwd();
  if (shortcut.needsProjectContext) {
    const isNext = await isNextProject(projectPath);
    if (!isNext) {
      // Fall back to default project path if current directory is not a Next.js project
      projectPath = preferences.defaultProjectPath;
      const isDefaultNext = await isNextProject(projectPath);
      if (!isDefaultNext) {
        await showToast(
          ToastStyle.Failure,
          'No Next.js Project Found',
          'Current directory and default project path are not Next.js 16 projects'
        );
        return;
      }
      await showToast(
        ToastStyle.Animated,
        'Using Default Project',
        `Current directory is not a Next.js project. Using ${projectPath}`
      );
    }
  }

  // Show loading toast for long-running operations
  const loadingToast = await showToast(
    ToastStyle.Animated,
    `Running: ${shortcut.title}`,
    'Executing shortcut...'
  );

  try {
    // Handle special cases for commands that need environment variables
    const env = { ...process.env };
    if (shortcut.id === 'deploy-vercel' && preferences.vercelToken) {
      env.VERCEL_TOKEN = preferences.vercelToken;
    }
    if (shortcut.id === 'analyze-bundle') {
      env.ANALYZE = 'true';
      env.BUNDLE_ANALYZER_PORT = preferences.bundleAnalyzerPort.toString();
    }

    // Execute the command using execa with project path as cwd
    const { stdout, stderr } = await execa(shortcut.command, shortcut.args, {
      cwd: shortcut.needsProjectContext ? projectPath : undefined,
      env,
      stdio: ['pipe', 'pipe', 'pipe']
    });

    // Dismiss loading toast
    loadingToast.hide();

    // Show success toast with output preview
    const outputPreview = stdout.length > 100 ? `${stdout.substring(0, 100)}...` : stdout;
    await showToast(
      ToastStyle.Success,
      `Success: ${shortcut.title}`,
      outputPreview || 'Operation completed successfully'
    );

    // Open bundle analyzer if analyze command was run
    if (shortcut.id === 'analyze-bundle') {
      await open(`http://localhost:${preferences.bundleAnalyzerPort}`);
    }

    // Log full output to console for debugging
    if (stdout) console.log(`[${shortcut.id}] STDOUT:`, stdout);
    if (stderr) console.error(`[${shortcut.id}] STDERR:`, stderr);

  } catch (error) {
    // Dismiss loading toast
    loadingToast.hide();

    // Execute custom error handler if defined, otherwise show default error
    if (shortcut.errorHandler) {
      await shortcut.errorHandler(error as Error);
    } else {
      await showToast(
        ToastStyle.Failure,
        `Failed: ${shortcut.title}`,
        (error as Error).message.substring(0, 100)
      );
    }

    // Log full error to console
    console.error(`[${shortcut.id}] ERROR:`, error);
  }
}

// Helper to list all available shortcuts for Raycast command list
export async function listShortcuts(): Promise {
  const currentProjectPath = process.cwd();
  const isNext = await isNextProject(currentProjectPath);

  return NEXT_16_SHORTCUTS.map(shortcut => ({
    ...shortcut,
    // Disable shortcuts that need project context if no project is found
    disabled: shortcut.needsProjectContext && !isNext
  }));
}

// Import Raycast UI components for the shortcut selector
import React from 'react';
import { List, ActionPanel, Action, Icon, Detail, showToast, ToastStyle } from '@raycast/api';
import { NEXT_16_SHORTCUTS } from './shortcut-registry';
import { executeShortcut, listShortcuts } from './shortcut-executor';
import { isNextProject } from './shortcut-registry';
import path from 'path';

// Main Raycast command component to list and execute Next.js 16 shortcuts
export default function Next16ShortcutsCommand() {
  // State to track shortcut list and project validation
  const [shortcuts, setShortcuts] = React.useState([]);
  const [isLoading, setIsLoading] = React.useState(true);
  const [projectValid, setProjectValid] = React.useState(false);

  // Load shortcuts and validate project on mount
  React.useEffect(() => {
    async function loadData() {
      try {
        setIsLoading(true);
        const shortcutList = await listShortcuts();
        setShortcuts(shortcutList);
        const currentPath = process.cwd();
        const valid = await isNextProject(currentPath);
        setProjectValid(valid);
      } catch (error) {
        await showToast(ToastStyle.Failure, 'Load Failed', (error as Error).message);
      } finally {
        setIsLoading(false);
      }
    }
    loadData();
  }, []);

  // Handle shortcut selection
  const handleSelectShortcut = async (shortcutId: string) => {
    await executeShortcut(shortcutId);
  };

  // Render empty state if no shortcuts are found (should never happen)
  if (!isLoading && shortcuts.length === 0) {
    return (

             window.location.reload()} />

        }
      />
    );
  }

  // Render main shortcut list
  return (

           {
              const selected = shortcuts.find(s => s.id === shortcuts[0].id);
              if (selected) handleSelectShortcut(selected.id);
            }}
          />

      }
    >
      {/* Section for project-specific shortcuts if project is valid */}
      {projectValid && (

          {shortcuts
            .filter(s => s.needsProjectContext)
            .map(shortcut => (

                     handleSelectShortcut(shortcut.id)}
                      icon={Icon.Play}
                    />
                     {
                        const cmd = `${shortcut.command} ${shortcut.args.join(' ')}`;
                        navigator.clipboard.writeText(cmd);
                        showToast(ToastStyle.Success, 'Copied', `Command copied to clipboard: ${cmd}`);
                      }}
                      icon={Icon.Clipboard}
                    />

                }
              />
            ))}

      )}

      {/* Section for global shortcuts */}

        {shortcuts
          .filter(s => !s.needsProjectContext)
          .map(shortcut => (

                   handleSelectShortcut(shortcut.id)}
                    icon={Icon.Play}
                  />
                   {
                      const cmd = `${shortcut.command} ${shortcut.args.join(' ')}`;
                      navigator.clipboard.writeText(cmd);
                      showToast(ToastStyle.Success, 'Copied', `Command copied to clipboard: ${cmd}`);
                    }}
                    icon={Icon.Clipboard}
                  />

              }
            />
          ))}


      {/* Project validation warning if no Next.js project found */}
      {!projectValid && (



      )}

  );
}

{
  "name": "start-dev-server",
  "title": "Start Next.js 16 Dev Server",
  "description": "Launch Next.js 16 development server on port 3000 with TurboPack enabled",
  "mode": "no-view",
  "hotkey": { "keys": ["cmd", "shift", "d"] }
}

{
  id: 'start-dev-server',
  title: 'Start Next.js 16 Dev Server',
  description: 'Launch Next.js 16 development server on port 3001 with Turbopack enabled',
  icon: Icon.Play,
  command: 'npm',
  args: ['run', 'dev', '--', '--turbo', '--port', '3001'],
  needsProjectContext: true,
  errorHandler: async (error) => {
    await showToast(ToastStyle.Failure, 'Dev Server Failed', `Server start failed: ${error.message}`);
  }
}

{
  id: 'build-production',
  title: 'Build Next.js 16 Production Bundle',
  description: 'Generate optimized production build with static site generation and incremental static regeneration',
  icon: Icon.Box,
  command: 'npm',
  args: ['run', 'build'],
  needsProjectContext: true,
  errorHandler: async (error) => {
    let retries = 2;
    while (retries > 0) {
      try {
        await execa('npm', ['run', 'build'], { cwd: process.cwd() });
        await showToast(ToastStyle.Success, 'Build Succeeded', 'Retry after initial failure succeeded');
        return;
      } catch (retryError) {
        retries--;
        if (retries === 0) {
          await showToast(ToastStyle.Failure, 'Build Failed', `Build failed after 2 retries: ${error.message}`);
        } else {
          await execa('rm', ['-rf', '.next'], { cwd: process.cwd() });
          await new Promise(resolve => setTimeout(resolve, 5000));
        }
      }
    }
  }
}

nextjs-16-raycast-shortcuts/
├── src/
│   ├── shortcut-registry.ts  # 16 shortcut definitions
│   ├── shortcut-executor.ts  # Execution logic with error handling
│   ├── next16-command.tsx    # Raycast UI component
│   └── utils/
│       └── project-validator.ts  # Next.js project validation
├── package.json
├── tsconfig.json
├── raycast-manifest.json
├── .eslintrc.json
├── jest.config.js
└── README.md