How to fix Hosting: Cannot deploy web framework from source - experiment not enabled in Firebase

The primary fix is to enable the webframeworks experimental feature:

Enable the experiment globally:

firebase experiments:enable webframeworks

This command enables the experiment for all Firebase projects on your machine.

Verify the experiment is enabled:

firebase experiments:list

You should see webframeworks listed as enabled:

Experiments:
  ✓ webframeworks - Framework-aware Hosting

Check your Firebase CLI version:

firebase --version

Ensure you're using Firebase CLI version 12.1.0 or later (12.4.0+ recommended for better framework support).

Update Firebase CLI if needed:

npm install -g firebase-tools

After enabling the experiment, try deploying again:

firebase deploy --only hosting

If deployment works locally but fails in CI/CD, you need to enable the experiment in your pipeline:

GitHub Actions workflow example:

name: Deploy to Firebase Hosting

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Install Firebase CLI
        run: npm install -g firebase-tools

      - name: Enable webframeworks experiment
        run: firebase experiments:enable webframeworks

      - name: Deploy to Firebase Hosting
        run: firebase deploy --only hosting --token ${{ secrets.FIREBASE_TOKEN }}
        env:
          FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }}

Key points:
1. Add the firebase experiments:enable webframeworks step BEFORE deployment
2. Ensure Firebase CLI is installed in the CI environment
3. Use Firebase token for authentication in CI/CD
4. Set the token as a GitHub secret

Generate Firebase token for CI/CD:

firebase login:ci

This generates a token you can use in FIREBASE_TOKEN secret.

Alternative: Use Firebase GitHub Action:

- name: Deploy to Firebase Hosting
  uses: FirebaseExtended/action-hosting-deploy@v0
  with:
    repoToken: '${{ secrets.GITHUB_TOKEN }}'
    firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}'
    channelId: live
    projectId: your-project-id
  env:
    FIREBASE_CLI_EXPERIMENTS: webframeworks

Set the environment variable FIREBASE_CLI_EXPERIMENTS: webframeworks to enable the experiment.

Check your firebase.json to ensure it's properly configured for framework deployment:

Framework-aware configuration (requires webframeworks experiment):

{
  "hosting": {
    "source": ".",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "frameworksBackend": {
      "region": "us-central1"
    }
  }
}

Key differences from static hosting:
- Uses "source": "." instead of "public": "dist" or "public": "build"
- Optional frameworksBackend for SSR configuration
- Firebase automatically detects framework (Next.js, Angular, etc.)

Static site configuration (doesn't require webframeworks):

{
  "hosting": {
    "public": "dist",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}

Mixed configuration (multiple hosting targets):
If you have both static and framework-based sites:

{
  "hosting": [
    {
      "target": "static-site",
      "public": "public",
      "ignore": ["firebase.json", "**/.*", "**/node_modules/**"]
    },
    {
      "target": "nextjs-app",
      "source": ".",
      "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
      "frameworksBackend": {
        "region": "us-central1"
      }
    }
  ]
}

Important: Ensure you're deploying the correct target:

firebase deploy --only hosting:nextjs-app

Common configuration issues:
- Missing "source" field for framework apps
- Using "public" when you should use "source"
- Incorrect framework detection due to missing framework config files
- Region not specified for frameworksBackend

If you're setting up a new project or need to reconfigure, properly initialize Firebase Hosting:

Initialize Firebase in your project:

# Enable webframeworks first
firebase experiments:enable webframeworks

# Initialize Firebase
firebase init hosting

During initialization:
1. Select "Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys"
2. When asked about framework detection, choose "Yes" if you want Firebase to auto-detect
3. Select your framework (Next.js, Angular, etc.) or let Firebase auto-detect
4. Choose deployment options (GitHub Actions, etc.)

For Next.js projects:

# Create Next.js app if needed
npx create-next-app@latest my-app
cd my-app

# Enable experiment
firebase experiments:enable webframeworks

# Initialize Firebase
firebase init hosting

# Select Next.js when prompted
# Firebase will configure firebase.json automatically

For Angular projects:

# Create Angular app if needed
ng new my-app
cd my-app

# Enable experiment
firebase experiments:enable webframeworks

# Initialize Firebase
firebase init hosting

# Select Angular when prompted

Manual framework configuration:
If auto-detection fails, you can manually configure in firebase.json:

{
  "hosting": {
    "source": ".",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "frameworksBackend": {
      "region": "us-central1",
      "maxInstances": 100,
      "minInstances": 0,
      "concurrency": 80
    }
  }
}

Verify framework detection:

firebase deploy --only hosting --debug

Look for lines indicating framework detection:

[debug] Detected Next.js framework
[debug] Building Next.js application...

Firebase App Hosting is now generally available (GA) and is the recommended approach for framework deployments:

Why consider App Hosting:
- Fully supported for production (not experimental)
- Better performance and scalability
- Native support for Next.js and Angular
- Improved build and deployment pipeline
- Production SLA and support

Check if App Hosting is right for you:
- You're deploying Next.js or Angular applications
- You need server-side rendering (SSR)
- You want production-grade support
- You're starting a new project

Initialize App Hosting instead:

firebase init apphosting

Key differences from framework-aware Hosting:
- App Hosting uses Cloud Run instead of Cloud Functions
- Better cold start performance
- Automatic scaling and load balancing
- Integrated CI/CD with GitHub
- No experimental flags needed

Migration from webframeworks to App Hosting:
1. Review the [App Hosting documentation](https://firebase.google.com/docs/app-hosting)
2. Backup your current configuration
3. Initialize App Hosting in your project
4. Test deployment to App Hosting
5. Update DNS/custom domains as needed

When to stay with framework-aware Hosting:
- You have an existing project that works well
- You don't want to migrate infrastructure
- You're using frameworks not yet supported by App Hosting
- You need specific Hosting features not available in App Hosting

Continue using webframeworks experiment:
If you choose to stay with framework-aware Hosting, ensure:
- All developers enable the experiment
- CI/CD pipelines include experiment enablement
- Document the requirement in your project README
- Monitor Firebase announcements for changes to experimental features

If enabling the experiment doesn't resolve the issue, try these troubleshooting steps:

1. Clear Firebase cache and retry:

# Clear Firebase cache
rm -rf .firebase/
rm -rf .next/  # For Next.js
rm -rf dist/   # For Angular

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Enable experiment again
firebase experiments:enable webframeworks

# Deploy
firebase deploy --only hosting

2. Check for conflicting Firebase CLI installations:

# Check which firebase is being used
which firebase

# Check for multiple installations
npm list -g firebase-tools

# Uninstall all versions
npm uninstall -g firebase-tools

# Reinstall latest version
npm install -g firebase-tools@latest

# Enable experiment
firebase experiments:enable webframeworks

3. Verify billing is enabled (required for SSR):
- Server-side rendering requires Cloud Functions
- Cloud Functions require Blaze (pay-as-you-go) plan
- Check Firebase Console > Usage and billing

4. Check Cloud Functions quota:

# Deploy with verbose logging
firebase deploy --only hosting --debug

Look for quota errors or function deployment failures.

5. Test with a simple framework app:
Create a minimal test project to isolate the issue:

# Create test Next.js app
npx create-next-app@latest test-app
cd test-app

# Enable experiment
firebase experiments:enable webframeworks

# Initialize Firebase
firebase init hosting

# Deploy
firebase deploy --only hosting

If this works, the issue is with your project configuration.

6. Check for framework version compatibility:
- Ensure your framework version is supported
- Update to latest framework version if possible
- Check [Firebase framework compatibility](https://firebase.google.com/docs/hosting/frameworks/frameworks-overview)

7. Review deployment logs:

firebase deploy --only hosting --debug 2>&1 | tee deploy.log

Review deploy.log for specific error messages or stack traces.