Svelte Migration Analysis Action

A powerful GitHub Action that helps teams migrate from Svelte 4 to Svelte 5 by analysing your codebase for deprecated patterns and providing actionable migration guidance. Get automated PR comments with detailed migration recommendations powered by static analysis and optional AI insights.

✨ Features

• 🔍 Static Analysis: Detects Svelte 4 patterns that need updating for Svelte 5
• 🤖 AI-Powered Insights: Optional Claude 4 analysis for detailed migration suggestions
• 💬 PR Comments: Automatic comments on pull requests with detailed findings
• ⚡ Fast Analysis: Built with TypeScript and optimised for large codebases
• 📊 Comprehensive Reports: Issues, warnings, and migration guidance
• 🎯 Configurable: Filter files, set failure conditions, and customise behaviour
• 🔧 Zero Config: Works out of the box with sensible defaults

🚀 Quick Start

Add this to your workflow file (.github/workflows/svelte-migration.yml):

name: Svelte Migration Analysis

on:
  pull_request:
    paths:
      - '**/*.svelte'
      - '**/*.ts'
      - '**/*.js'

jobs:
  svelte-migration:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Analyse Svelte Migration
        uses: spences10/svelte-migration-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

🔧 Repository Setup

Important: To enable PR comments and full functionality, you need to configure your repository permissions:

Required GitHub Repository Settings

1. Workflow Permissions (Settings → Actions → General → Workflow permissions):

   • Select "Read and write permissions"
   • ✅ Check "Allow GitHub Actions to create and approve pull requests"

2. Why these permissions are needed:

   • Read and write permissions: Allows the action to post comments on pull requests
   • Create and approve pull requests: Enables the action to interact with PR comments and reviews

Without these settings enabled:

• ❌ You'll see: HttpError: Resource not accessible by integration
• ❌ No PR comments will be created
• ✅ Analysis will still run and output results to the workflow logs

Alternative Permission Configuration

If you prefer more granular control, you can add explicit permissions to your workflow:

jobs:
  svelte-migration:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
    steps:
      # ... rest of your workflow

📋 What It Detects

The action identifies common Svelte 4 patterns that need updating:

🔴 Breaking Changes (Errors)

• createEventDispatcher usage → Use callback props
• beforeUpdate/afterUpdate lifecycle hooks → Use $effect.pre() and $effect()
• Component instantiation with new → Use mount() or hydrate()
• $$props and $$restProps → Use destructuring with $props()
• $$slots usage → Use snippet parameters

⚠️ Deprecations (Warnings)

• Reactive statements ($:) → Replace with $derived or $effect
• export let declarations → Replace with $props()
• on: event directives → Replace with event properties
• Named slots → Replace with snippets
• Store auto-subscriptions → Consider $state for reactive variables
• Event modifiers → Handle in event handlers directly

⚙️ Configuration

Inputs

Outputs

🎯 Advanced Configuration

Custom Paths

- name: Analyse Svelte Migration
  uses: spences10/svelte-migration-action@v1
  with:
    paths: |
      src/components
      src/routes
      lib
    exclude-paths: |
      node_modules
      .svelte-kit
      build
      dist
      test

Strict Mode (Fail on Issues)

- name: Analyse Svelte Migration
  uses: spences10/svelte-migration-action@v1
  with:
    fail-on-error: true
    fail-on-warning: true

AI-Powered Analysis

- name: Analyse Svelte Migration
  uses: spences10/svelte-migration-action@v1
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    enable-ai-analysis: true

🤖 AI Analysis Setup

For enhanced migration suggestions powered by Claude 4:

1. Get an Anthropic API key from console.anthropic.com
2. Add it to your repository secrets as ANTHROPIC_API_KEY
3. Enable AI analysis in your workflow:

with:
  anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
  enable-ai-analysis: true

The AI will provide:

• Detailed code transformation examples
• Context-aware migration suggestions
• Best practices for Svelte 5 patterns
• Performance optimisation tips

📊 Example Output

When the action runs, it will:

1. Analyse your Svelte files for migration patterns
2. Generate a detailed report with line-by-line findings
3. Post a PR comment with actionable recommendations

Sample PR Comment:

# 🔄 Svelte Migration Analysis Results

## 📊 Summary

- **Files analysed:** 15
- **Issues found:** 3
- **Warnings found:** 8

## ❌ Issues (3)

These are breaking changes that must be addressed for Svelte 5:

<details>
<summary>📄 <code>src/components/Modal.svelte</code> - 1 issue</summary>

- **Line 15:** createEventDispatcher is deprecated in Svelte 5
  - 💡 **Suggestion:** Use callback props instead of
    createEventDispatcher

</details>

<details>
<summary>📄 <code>src/routes/+page.svelte</code> - 2 issues</summary>

- **Line 23:** beforeUpdate/afterUpdate are deprecated in Svelte 5
  - 💡 **Suggestion:** Use $effect.pre() and $effect() instead
- **Line 30:** $$props and $$restProps are deprecated
  - 💡 **Suggestion:** Use destructuring with rest in $props(): let {
    foo, ...rest } = $props()

</details>

## ⚠️ Warnings (8)

These patterns will still work but are deprecated in Svelte 5:

<details>
<summary>📄 <code>src/components/Button.svelte</code> - 5 warnings</summary>

- **Line 5:** export let should be replaced with $props()
  - 💡 **Suggestion:** Replace with: let { propName } = $props()
- **Line 10:** Reactive statement ($:) should be replaced with
  $derived or $effect
  - 💡 **Suggestion:** Use $derived for computed values or $effect for
    side effects
- **Line 22:** on: event directives should be replaced with event
  properties
  - 💡 **Suggestion:** Replace on:click with onclick

</details>

<details>
<summary>📄 <code>src/components/Input.svelte</code> - 3 warnings</summary>

- **Line 8:** export let should be replaced with $props()
  - 💡 **Suggestion:** Replace with: let { propName } = $props()
- **Line 15:** Named slots should be replaced with snippets
  - 💡 **Suggestion:** Use {#snippet name()} and {@render name()}
    instead

</details>

## 📚 Migration Resources

- [Svelte 5 Migration Guide](https://svelte.dev/docs/svelte/v5-migration-guide)
- [Automatic Migration Tool](https://svelte.dev/docs/svelte/v5-migration-guide#migration-script):
  `npx sv migrate svelte-5`
- [Svelte 5 Documentation](https://svelte.dev/docs/svelte)

🛠️ Development

Local Development

# Clone the repository
git clone https://github.com/spences10/svelte-migration-action.git
cd svelte-migration-action

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the action
pnpm build

# Package for distribution
pnpm package

Testing

# Run all tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run linting
pnpm lint

# Format code
pnpm format

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Ensure all tests pass: pnpm test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

📄 Licence

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

🙏 Acknowledgements

• Inspired by svelte-check-action
• Built with love for the Svelte community

🔗 Related Projects

• Svelte 5 Migration Guide
• svelte-check
• Svelte Language Tools

Made with ❤️ for the Svelte community

Help teams migrate to Svelte 5 with confidence! 🚀