Astro 5.5: A Deep Dive into Diagramming Tools, Type-Safe Sessions, and More

Abdul Aziz Ahwan
15 Mar, 2025

The Astro team has done it again! Astro 5.5 is here, bringing a wave of enhancements designed to streamline your development workflow, improve compatibility, and empower you to build faster, safer, and more visually engaging websites. Whether you’re a seasoned Astro developer or just starting your journey, this release packs features that will elevate your projects.

In this comprehensive guide, we’ll explore everything Astro 5.5 has to offer, from its game-changing support for diagramming tools to its experimental type-safe sessions. Plus, we’ll walk you through upgrading your project and share pro tips for maximizing these new features. Let’s dive in!

Why Astro 5.5 Matters

Astro has rapidly become a favorite among developers for its component-driven architecture, lightning-fast performance, and Markdown-first approach. With version 5.5, the framework doubles down on flexibility and developer experience. Here’s why this update is a must-have:

  • Rich Visual Documentation: Seamlessly integrate diagrams into your Markdown content.
  • Type Safety: Catch errors early with typed session data.
  • Consistent Cross-Platform Output: Align heading IDs with GitHub and npm standards.
  • Predictable Styling: Preserve the order of <style> and <script> tags.

Ready to explore these features in detail? Let’s break them down!

Key Features of Astro 5.5

Better Support for Diagramming Tools in Markdown

What’s New?

Astro 5.5 introduces native support for diagramming tools like Mermaid and D2. These tools let you create flowcharts, sequence diagrams, and other visualizations directly in Markdown code blocks. Previously, Astro’s syntax highlighting interfered with their rendering, forcing developers to disable highlighting globally. Now, you can exclude specific languages from syntax highlighting using the excludeLangs option.

Why It Matters

  • No More Workarounds: Skip complex configurations to integrate diagrams.
  • Visual Documentation: Enhance technical blogs, API docs, or project roadmaps with dynamic visuals.
  • Selective Exclusion: Keep syntax highlighting for other code blocks (e.g., JavaScript, Python).

How to Use It

  1. Install a Rehype Plugin: For Mermaid, use rehype-mermaid.
  2. Update Your Config:
    ```typescript
    // astro.config.mjs
    import { defineConfig } from 'astro/config';
    import rehypeMermaid from 'rehype-mermaid';

export default defineConfig({
markdown: {
syntaxHighlight: {
type: 'shiki',
excludeLangs: ['mermaid', 'd2'], // Exclude languages from highlighting
},
rehypePlugins: [rehypeMermaid], // Add your diagram plugin
},
}); 

3. **Create Diagrams in Markdown**:  
````markdown  
```mermaid  
graph TD  
    A[Start] --> B{Is it working?}  
    B -->|Yes| C[Great!]  
    B -->|No| D[Debug]  
    D --> B


#### Pro Tip  
Pair this with [Obsidian](https://obsidian.md/)-style note-taking to create interactive documentation that’s both human-readable and visually engaging.  

---

### 2. Type-Safe Experimental Sessions  

#### What’s New?  
Astro 5.5 brings TypeScript support to experimental sessions, allowing you to define strict types for session data. Previously, session values were loosely typed as `any`, leading to potential runtime errors. Now, you can enforce type safety by extending the `App.SessionData` interface.  

#### Why It Matters  
- **Early Error Detection**: Catch mismatched types during development.  
- **Improved Autocomplete**: Enjoy IDE support for session keys and values.  
- **Structured Data**: Define clear contracts for user sessions (e.g., `user.id`, `lastLogin`).  

#### How to Use It  
1. **Define Session Types**:  
```typescript  
// src/env.d.ts  
declare namespace App {  
  interface SessionData {  
    user: {  
      id: string;  
      email: string;  
    };  
    lastLogin: Date;  
  }  
}
  1. Access Typed Data:
    ```astro

// pages/dashboard.astro
const user = await Astro.session.get('user'); // Type: { id: string; email: string } | undefined
const lastLogin = await Astro.session.get('lastLogin'); // Type: Date | undefined

// TypeScript will flag invalid assignments

Astro.session.set('user', 1); // Error: Expected object, got number 


#### Pro Tip  
Combine this with Astro’s [authentication integrations](https://docs.astro.build/en/guides/integrations-guide/auth/) to build secure, type-checked user workflows.  

---

### 3. Improved Heading ID Compatibility  

#### What’s New?  
Astro 5.5 introduces the `experimental.headingIdCompat` flag, aligning heading ID generation with platforms like GitHub and npm. Previously, Astro trimmed trailing dashes in IDs (e.g., `## Hello--` became `#hello`), causing inconsistencies when cross-linking documentation.  

#### Why It Matters  
- **Consistent Anchors**: Ensure links work across your site, GitHub repos, and npm packages.  
- **SEO Benefits**: Avoid duplicate content issues from mismatched anchor links.  

#### How to Use It  
Enable the flag in your Astro config:  
```typescript  
// astro.config.mjs  
import { defineConfig } from 'astro/config';  

export default defineConfig({  
  experimental: {  
    headingIdCompat: true,  
  },  
});

Example

  • Before: ## Getting Started-- → #getting-started
  • After: ## Getting Started-- → #getting-started--

Experimental: Preserve Order of Style and Script Tags

What’s New?

The experimental.preserveScriptOrder flag ensures <style> and <script> tags render in the order they’re defined. Previously, Astro reversed their order, leading to unexpected styling issues (e.g., later styles overriding earlier ones in production).

Why It Matters

  • Predictable Styling: Write CSS without worrying about build-time reversals.
  • Script Dependencies: Safely load libraries that depend on execution order.

How to Use It

// astro.config.mjs  
import { defineConfig } from 'astro/config';  

export default defineConfig({  
  experimental: {  
    preserveScriptOrder: true,  
  },  
});

Pro Tip

Test this flag early! It’s expected to become the default in future releases.

How to Upgrade to Astro 5.5

Upgrading is a breeze with the @astrojs/upgrade CLI: 

# Recommended (automated)  
npx @astrojs/upgrade  

# Manual  
npm install astro@latest  
pnpm upgrade astro --latest  
yarn upgrade astro --latest

Before Upgrading:

Bug Fixes & Enhancements

Astro 5.5 also squashes several bugs from previous releases:

  • Fixed getStaticPaths type inference in .mdx files.
  • Resolved Astro.url inconsistencies in dev mode.
  • Patched security vulnerabilities in the dev server.

For a full list, check the official changelog.

Community Contributions

A huge thanks to the Astro community for their contributions:

  • Chris Chua: Spearheaded diagramming tool support.
  • Reuben Tier: Fixed script order preservation.
  • Bjorn Lu: Enhanced TypeScript tooling.

Join the Astro Discord to share your feedback!

Conclusion

Astro 5.5 is a testament to the framework’s commitment to developer experience and innovation. Whether you’re visualizing data with Mermaid, fortifying sessions with TypeScript, or ensuring consistent anchors across platforms, this release empowers you to build smarter and faster.

Ready to get started? Upgrade today and unleash the full potential of Astro 5.5!

🚀 Discover endless inspiration for your next project with Mobbin’s stunning design resources and seamless systems—start creating today!

More Astro Releases:

  • Astro 5.4: Remote image optimization, enhanced security.
  • Astro 5.3: Faster rendering, easier session setup.

Looking Ahead:
Stay tuned for Astro 5.6, which promises even more performance optimizations and developer tools!

Have questions? Drop a comment below or reach out on Twitter!

Next Post Previous Post
No Comment
Add Comment
comment url
mobbin
screen-studio