Skip to Content
📚 MyStoryFlow Docs — Your guide to preserving family stories

Deployment Troubleshooting

This guide covers common deployment issues and their solutions for the MyStoryFlow monorepo.

Common Issues

1. Nextra Build Errors

Error: “nextra is not a function”

Problem: Using Nextra 3.x configuration with Nextra 4.0

Root Cause: Nextra 4.0 introduced breaking changes and requires App Router instead of Pages Router.

Solution: Migrate to Nextra 4.0 configuration:

  1. Update next.config.js to next.config.mjs with ES modules:
// next.config.mjs
import nextra from 'nextra'
 
const withNextra = nextra({
  // Add Nextra-specific options here
})
 
export default withNextra({
  transpilePackages: ['nextra', 'nextra-theme-docs'],
  images: {
    unoptimized: true,
  },
})
``` -->
 
2. **Create App Router layout** (`app/layout.jsx`):
 
```jsx
import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'
 
export const metadata = {
  title: 'Your Documentation',
  description: 'Your documentation description',
}
 
export default async function RootLayout({ children }) {
  return (
    <html lang="en" dir="ltr" suppressHydrationWarning>
      <Head />
      <body>
        <Layout
          navbar={<Navbar logo={<b>Your Logo</b>} />}
          pageMap={await getPageMap()}
          footer={<Footer>© Your Company</Footer>}
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}
``` -->
 
3. **Add mdx-components.jsx**:
 
```jsx
import { useMDXComponents as getComponents } from 'nextra-theme-docs'
 
export function useMDXComponents(components) {
  return getComponents(components)
}
``` -->
 
4. **Migrate content from pages/ to app/**:
   - Move `pages/index.mdx` to `app/page.mdx`
   - Move other content directories to `app/`
   - Update file-based routing as needed
 
#### Error: "require(...) is not a function"
 
**Problem**: Using CommonJS require syntax with ES modules
 
**Solution**: Use ES module imports in `next.config.mjs`:
 
```javascript
// ❌ Incorrect (CommonJS)
const nextra = require('nextra')
 
// âś… Correct (ES modules)
import nextra from 'nextra'
``` -->
 
#### Error: "Failed to load next.config.js"
 
**Problem**: Configuration file extension or syntax issues
 
**Solution**:
 
1. Rename `next.config.js` to `next.config.mjs`
2. Use ES module syntax throughout
3. Ensure proper import/export statements
 
### 2. Selective Deployment Not Working
 
#### Problem: All apps building on every commit
 
**Root Cause**: The `ignoreCommand` property in `vercel.json` files is invalid. Selective deployment must be configured in the Vercel Dashboard, not in `vercel.json`.
 
**Solution**: Configure ignore build step in Vercel Dashboard for each project:
 
1. **Go to Project Settings**:
 
   - Navigate to your Vercel dashboard
   - Select each project (web-app, marketing-site, docs-app, admin-app, tools-app)
   - Go to Settings → Git
 
2. **Configure Ignored Build Step**:
 
   - In the "Ignored Build Step" section, select "Custom"
   - Enter the command: `npx turbo-ignore`
   - Save the settings
 
3. **Repeat for All Projects**:
   - web-app: `npx turbo-ignore`
   - marketing-site: `npx turbo-ignore`
   - docs-app: `npx turbo-ignore`
   - admin-app: `npx turbo-ignore`
   - tools-app: `npx turbo-ignore`
 
**Important**: The `ignoreCommand` property in `vercel.json` is for overriding dashboard settings, not for initial configuration. Remove any `ignoreCommand` entries from your `vercel.json` files.
 
#### Verifying Selective Deployment
 
To test if selective deployment is working:
 
1. Make a change that only affects one app (e.g., edit a file in `apps/web-app/`)
2. Commit and push the change
3. Check the Vercel dashboard - only the affected app should build
4. Other apps should show "Build skipped" or similar status
 
### 3. Turbo Configuration Errors
 
#### Error: "Found 'pipeline' field instead of 'tasks'"
 
**Problem**: Using legacy Turbo configuration format
 
**Solution**: Update `turbo.json` to use modern format:
 
```json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    }
  }
}
``` -->
 
### 4. Node.js Version Compatibility
 
#### Error: "Node.js version required"
 
**Problem**: Local Node.js version incompatibility
 
**Local Development**: Upgrade Node.js to 18.18.0+ or 20+
**Vercel Deployment**: This doesn't affect Vercel builds (they use Node.js 20+)
 
### 5. Environment Variables
 
#### Missing environment variables in builds
 
**Problem**: Environment variables not properly configured
 
**Solution**: Ensure all required environment variables are set in:
 
1. Vercel Dashboard → Project Settings → Environment Variables
2. `turbo.json` globalEnv section for build-time variables
 
#### Warning: Environment variables missing from turbo.json
 
**Problem**: Vercel shows warnings about environment variables not in `turbo.json`
 
**Solution**: Add the missing environment variables to your `turbo.json`:
 
```json
{
  "globalEnv": [
    "POSTGRES_DATABASE",
    "POSTGRES_HOST",
    "POSTGRES_PASSWORD",
    "POSTGRES_PRISMA_URL",
    "DATABASE_URL",
    "POSTGRES_URL_NON_POOLING",
    "POSTGRES_USER",
    "SUPABASE_ANON_KEY",
    "SUPABASE_JWT_SECRET",
    "SUPABASE_URL",
    "RESEND_FROM_EMAIL",
    "B2_KEY_ID",
    "B2_APP_KEY",
    "B2_BUCKET_NAME",
    "B2_BUCKET_ID",
    "B2_BUCKET_URL",
    "NOTION_BLOG_DATABASE_ID",
    "CRON_SECRET"
  ]
}
``` -->
 
## Testing Your Configuration
 
### Local Testing
 
```bash
# Test turbo-ignore locally
cd apps/web-app
npx turbo-ignore
 
# Should exit with code 0 (skip) or 1 (build)
echo $?
``` -->
 
### Deployment Testing
 
1. Make a small change to one app
2. Commit and push
3. Monitor Vercel dashboard for selective builds
4. Check build logs for "turbo-ignore" execution
 
## Quick Fixes Checklist
 
- [ ] Remove `ignoreCommand` from all `vercel.json` files
- [ ] Configure "Ignored Build Step" in Vercel Dashboard for each project
- [ ] Use modern `tasks` format in `turbo.json`
- [ ] Ensure `turbo-ignore` package is installed in root `package.json`
- [ ] Verify environment variables are properly configured
- [ ] Test selective deployment with targeted changes
- [ ] Migrate to Nextra 4.0 if using Nextra (ES modules + App Router)
 
## Nextra 4.0 Migration Checklist
 
- [ ] Rename `next.config.js` to `next.config.mjs`
- [ ] Convert to ES module syntax (`import` instead of `require`)
- [ ] Create `app/layout.jsx` with proper Nextra 4.0 structure
- [ ] Add `mdx-components.jsx` file
- [ ] Move content from `pages/` to `app/` directory
- [ ] Update `pages/index.mdx` to `app/page.mdx`
- [ ] Test build locally and on Vercel
 
## Getting Help
 
If selective deployment still isn't working after following these steps:
 
1. Check the build logs in Vercel Dashboard for turbo-ignore execution
2. Verify the turbo-ignore command runs successfully locally
3. Ensure your monorepo structure matches Turborepo conventions
4. For Nextra issues, refer to [Nextra 4.0 documentation](https://nextra.site/docs/docs-theme/start)
5. Contact Vercel support with specific build logs and configuration details
 
## Debugging Commands
 
### Test Turbo-Ignore Locally
 
```bash
# From app directory
cd apps/your-app
npx turbo-ignore
 
# Check what turbo detects
npx turbo run build --filter=your-app --dry-run
``` -->
 
### Check Build Dependencies
 
```bash
# See what would build
npx turbo run build --dry-run
 
# Check specific app dependencies
npx turbo run build --filter=your-app --dry-run
``` -->
 
### Verify Selective Deployment
 
```bash
# Run our impact analysis
npm run deploy:check
 
# Check vercel.json configurations
find apps -name "vercel.json" -exec cat {} \;
``` -->
 
## Deployment Impact Analysis
 
Use our custom script to check which apps will be affected:
 
```bash
npm run deploy:check
``` -->
 
This script simulates the turbo-ignore logic and shows:
 
- Which apps have changes
- What dependencies are affected
- Expected deployment behavior
 
## Best Practices
 
### 1. Testing Changes
 
1. **Test locally**: Verify builds work (when Node.js version allows)
2. **Check turbo-ignore**: Test selective deployment logic
3. **Review dependencies**: Ensure changes don't affect unrelated apps
 
### 2. Configuration Management
 
1. **Keep turbo.json minimal**: Only include necessary global dependencies
2. **Use .vercelignore**: Exclude files that shouldn't trigger builds
3. **Test configuration changes**: Verify they don't break selective deployment
 
### 3. Monitoring Deployments
 
1. **Watch Vercel dashboard**: Monitor build times and success rates
2. **Check deployment logs**: Look for unexpected builds
3. **Review git history**: Understand what triggered deployments
 
## Emergency Procedures
 
### If All Apps Are Building Unexpectedly
 
1. **Check recent commits**: Look for global file changes
2. **Verify turbo.json**: Ensure configuration is correct
3. **Test turbo-ignore**: Verify it's working for each app
4. **Review environment variables**: Check for global changes
 
### If Builds Are Failing
 
1. **Check Node.js compatibility**: Ensure Vercel is using correct version
2. **Verify dependencies**: Ensure all packages are properly installed
3. **Test configuration**: Verify next.config.js and other configs
4. **Check environment variables**: Ensure all required vars are set
 
### If Selective Deployment Stops Working
 
1. **Verify ignoreCommand**: Ensure all vercel.json files have it
2. **Check turbo version**: Ensure compatibility
3. **Test turbo-ignore**: Verify it returns correct exit codes
4. **Review global dependencies**: Minimize unnecessary globals
 
---
 
This troubleshooting guide should help resolve most deployment issues. For additional help, check the deployment logs in Vercel and the git history to understand what triggered the builds.