Next.js → Avenx.js: Data Fetching and Async Boundaries Migration Guide

[nathanschmid08]

Overview

Next.js leverages Server Components (RSC), getServerSideProps, and getStaticProps for server-side data fetching. Avenx-JS is a client-side rendering (CSR) framework that manages async data loading declaratively using the <resource> SFC tag, Resource class, and <@suspense> / <@errorBoundary> containers.

This issue focuses on documenting data fetching migration inside the main Next.js migration guide file: docs/src/content/docs/migration/nextjs.md.

Goal

Expand Section 3 ("Data Fetching and Async Boundaries") in docs/src/content/docs/migration/nextjs.md.

What to document

1. Server to Client Data Fetching: Replacing RSC / getServerSideProps server fetches with client REST API calls inside <resource> tags.
2. Declarative Suspense: Wrapping async resource rendering in <@suspense> with <@fallback> markup.
3. Error Boundaries: Using <@errorBoundary> with <@fallback as="err"> to catch client fetch errors.
4. Auto-Refetching on State Change: How resources track reactive state variables automatically without manual re-fetch calls.
5. Background Polling: Configuring pollInterval on <resource>.

Required examples

Before – Next.js Server Component Fetch

// app/dashboard/page.tsx (Server Component)
async function getDashboardData() {
  const res = await fetch('https://api.example.com/stats', { cache: 'no-store' });
  if (!res.ok) throw new Error('Failed to fetch');
  return res.json();
}

export default async function DashboardPage() {
  const stats = await getDashboardData();
  return (
    <div>
      <h1>Total Users: {stats.users}</h1>
    </div>
  );
}

After – Avenx.js Resource & Suspense

<!-- src/pages/dashboard.page.js -->
<resource name="stats">
  return fetch('https://api.example.com/stats').then(res => {
    if (!res.ok) throw new Error('Failed to fetch dashboard stats');
    return res.json();
  });
</resource>

<div class="dashboard">
  <@errorBoundary>
    <@suspense>
      <h1>Total Users: {{ stats.value.users }}</h1>
      <@fallback>
        <p>Loading dashboard metrics...</p>
      </@fallback>
    </@suspense>
    <@fallback as="err">
      <p class="error">Error loading metrics: {{ err.message }}</p>
    </@fallback>
  </@errorBoundary>
</div>

Key Conceptual Differences & Pitfalls

• CSR Paradigm: Avenx executes templates and resources entirely in the browser. Database secrets or private backend credentials must NOT be placed inside <resource> blocks; fetch endpoints must call external REST/GraphQL APIs.
• Accessing Resource Value: Access resolved resource payload data using resourceName.value inside <@suspense> blocks.
• Suspense Fallback Tag: The fallback UI must be defined inside <@suspense> using the <@fallback> tag.

Difficulty

Good First Issue

Scope

• In Scope: Updating Section 3 in docs/src/content/docs/migration/nextjs.md for <resource>, <@suspense>, and <@errorBoundary>.
• Out of Scope: Creating new Markdown files or editing other framework migration files.

Expected Result

Section 3 in docs/src/content/docs/migration/nextjs.md is expanded with comprehensive data fetching documentation.

Acceptance Criteria

• Updated Section 3 in docs/src/content/docs/migration/nextjs.md
• At least 2 Before/After code examples (RSC Fetch to Resource, Resource with Suspense and Error Boundary)
• Client-side execution model and security considerations explicitly highlighted
• Links to docs/src/content/docs/core-concepts/resources.md and migration/overview.md
• Documentation build succeeds without errors