Common Pitfalls When Using TypeScript in Laravel Breeze or Jetstream

Introduction: Why This Matters in 2025

Laravel Breeze and Jetstream are two of the most popular starter kits in the Laravel ecosystem. They offer rapid scaffolding for modern web apps using Inertia.js, Vue 3 (or React), TailwindCSS, and Vite. But once TypeScript enters the picture, many developers stumble.

This article is your 2025 guide to avoiding the most common mistakes when working with TypeScript in Laravel Breeze or Jetstream setups.

Type safety is great—until it breaks your build because of mismatched types, missing declarations, or untyped props.

Key Takeaways

Understand typical TypeScript pain points in Laravel starter kits
Learn how to fix typing issues with Vue 3, Inertia, and shared props
Improve code quality and team productivity
Get actionable tips that apply in 2025 and beyond

Top Pitfalls Using TypeScript with Breeze or Jetstream

1. Not Using `<script lang="ts">` in Vue Components

Problem: Developers forget or skip using lang="ts" in Vue Single File Components (SFCs).

Solution:

<script lang="ts">
import { defineComponent } from 'vue';
</script>

2. Missing Type Definitions for Inertia Props

Problem: Using defineProps() without declaring prop types causes TS to infer any.

Fix:

interface User {
  id: number;
  name: string;
}
defineProps<{ user: User }>();

3. Forgetting to Configure `shims-vue.d.ts`

Problem: Vue files throw errors like “Cannot find module .vue”.

Fix: Create this file:

// shims-vue.d.ts
declare module '*.vue' {
  import { DefineComponent } from 'vue';
  const component: DefineComponent<{}, {}, any>;
  export default component;
}

4. Incorrect Vite + TS Configuration

Problem: TypeScript compiler or Vite build fails unexpectedly.

Fix: Use this minimal vite.config.ts:

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import path from 'path';
export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'resources/js')
    }
  }
});

5. Skipping Strict Mode in `tsconfig.json`

Problem: TypeScript defaults to loose settings if not configured.

Fix: Use strict options:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

6. Global Inertia Page Props Aren’t Typed

Problem: Page props accessed through usePage().props.value have no types.

Fix:

interface AppProps {
  auth: {
    user: {
      id: number;
      name: string;
    }
  }
}
const { auth } = usePage<AppProps>().props.value;

7. Typing Authenticated User Incorrectly

Problem: TS errors when accessing user properties like user.name without proper interface.

Fix: Define a reusable user interface in a types folder.

// types/User.ts
export interface User {
  id: number;
  name: string;
  email: string;
}

Helpful Table – Mistakes vs Fixes

Mistake	Fix
Using `<script>` instead of `<script lang="ts">`	Always add `lang="ts"`
Untyped Inertia props	Use `defineProps<{ type }>()`
Missing `.d.ts` shim file	Create `shims-vue.d.ts`
Vite + TS errors	Use proper `vite.config.ts`
Loose `tsconfig.json`	Enable `strict` mode
Untyped `usePage().props`	Add interface to `usePage<AppProps>()`

Real-World Scenario

You install Laravel Jetstream with Inertia + Vue:

composer require laravel/jetstream
php artisan jetstream:install inertia
npm install && npm run dev

You add TypeScript and convert your files. Everything breaks:

Components can’t read props
Pages throw undefined errors
Type checking fails on usePage()

This article’s tips solve all of those problems.

Best Practices Moving Forward

✅ Create a `/types` Directory

Centralize your TypeScript interfaces.

✅ Use Aliases in `tsconfig.json`

"paths": {
  "@": ["./resources/js"]
}

✅ Prefer Composition API

const props = defineProps<{ user: User }>();

✅ Type Your Global Props

Explicitly define shared Inertia props in app.ts or global declaration files.

FAQ

Do I have to rewrite all Vue files to TypeScript?

No. You can migrate gradually, starting with key components.

Can TypeScript work with React in Jetstream?

Yes. TypeScript works well with both Vue and React in Jetstream.

Does Breeze support TypeScript out of the box?

No, but it’s easy to integrate with minimal config.

What about typing Laravel API responses?

Use shared DTOs or define interfaces for expected shapes.

Helpful Resources

Conclusion

Using TypeScript with Laravel Breeze or Jetstream in 2025 is a smart move—but not without its quirks.

The good news? Every issue has a solution. Whether you’re facing build errors, untyped props, or Vite config headaches, this guide equips you to work smarter, not harder.

Start small, refactor incrementally, and create reusable types to level up your frontend architecture.

Need help setting this up for your Laravel app? Contact us for Laravel + TS consulting.