@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/remix/configuration/dont-subcomponent-network.md

@@ -0,0 +1,166 @@
+---
+meta:
+    title: Don't write network requests over the sub components.
+    description: Don't write network requests over the sub components.
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Don't write network requests over the sub components....
+headers:
+    Cache-Control: no-cache
+---
+
+### Don't Do Case
+
+#### SubComponent with GraphQL Query
+
+In this case, the `SubComponent` handles the GraphQL query directly, which should be avoided:
+
+```javascript
+// SubComponent.js
+import { gql, useQuery } from '@apollo/client';
+
+const GET_USERS = gql`
+    query GetUsers {
+        users {
+            id
+            name
+            email
+        }
+    }
+`;
+
+function SubComponent() {
+    const { data, loading, error } = useQuery(GET_USERS);
+
+    if (loading) return <p>Loading...</p>;
+    if (error) return <p>Error: {error.message}</p>;
+
+    return (
+        <div>
+            <h1>Users</h1>
+            <ul>
+                {data.users.map((user) => (
+                    <li key={user.id}>
+                        {user.name} ({user.email})
+                    </li>
+                ))}
+            </ul>
+        </div>
+    );
+}
+
+export default SubComponent;
+```
+
+#### Main Page Importing SubComponent
+
+The main page simply imports and uses `SubComponent`, without handling the data fetching properly.
+
+```javascript
+// mainPage.js
+import SubComponent from './SubComponent';
+
+export default function MainPage() {
+    return (
+        <div>
+            <SubComponent />
+        </div>
+    );
+}
+```
+
+### Do Case
+
+#### Step-by-Step Refactor
+
+1. **Define the GraphQL Query in the Main Page**
+
+```javascript
+// mainPage.js
+import { gql } from '@apollo/client';
+
+const GET_USERS = gql`
+    query GetUsers {
+        users {
+            id
+            name
+            email
+        }
+    }
+`;
+```
+
+2. **Set Up the Loader Function**
+
+```javascript
+// mainPage.js
+import { json, LoaderFunction } from '@remix-run/node';
+import { useLoaderData } from '@remix-run/react';
+import { initializeApollo } from '~/utils/apolloClient'; // Utility to initialize Apollo Client
+import SubComponent from './SubComponent';
+
+// instead you can also use graphql Query directly with fetch policy set to cache-only to auto generate loaders as described in `generated-data-loaders`
+export let loader: LoaderFunction = async () => {
+    const client = initializeApollo();
+    try {
+        const { data } = await client.query({ query: GET_USERS });
+        return json(data);
+    } catch (error) {
+        console.error('Error fetching users:', error);
+        throw new Response('Error fetching users', { status: 500 });
+    }
+};
+```
+
+3. **Create the SubComponent as a Pure Component**
+
+```javascript
+// SubComponent.js
+function SubComponent({ users }) {
+    return (
+        <div>
+            <h1>Users</h1>
+            <ul>
+                {users.map((user) => (
+                    <li key={user.id}>
+                        {user.name} ({user.email})
+                    </li>
+                ))}
+            </ul>
+        </div>
+    );
+}
+
+export default SubComponent;
+```
+
+4. **Use the SubComponent in the Main Page**
+
+```javascript
+// mainPage.js
+import { useLoaderData } from '@remix-run/react';
+import SubComponent from './SubComponent';
+
+export default function MainPage() {
+    const { users } = useLoaderData();
+
+    return (
+        <div>
+            <SubComponent users={users} />
+        </div>
+    );
+}
+```
+
+### Summary
+
+**Don't Do Case:**
+
+- Placing GraphQL queries inside subcomponents makes it harder to manage data flow and breaks SSR benefits.
+- Subcomponents are not pure and are tightly coupled with data-fetching logic.
+
+**Do Case:**
+
+- GraphQL queries are centralized in the main routed page's loader.
+- Data fetching is handled during SSR, improving performance.
+- Subcomponents are kept pure and receive data via props, making them more reusable and easier to test.

package/lib/templates/content/docs/remix/configuration/generated-data-loaders.md

@@ -0,0 +1,122 @@
+---
+meta:
+    title: Generated Data Loaders
+    description: Generated Data Loaders
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Generated Data Loaders...
+headers:
+    Cache-Control: no-cache
+---
+
+# Generated Data Loaders
+
+To minimize repetitive work, we automatically generate Remix data loaders by analyzing the page source code. Our parser scans the page for GraphQL queries and calls all of those queries in the generated data loaders.
+
+## How It Works
+
+1. The parser analyzes the component code and detects GraphQL queries.
+2. It creates a key-value pair where the key represents the GraphQL document the query uses, and the value refers to the variables used by the query.
+3. This information is used to generate both server and client loaders.
+
+## Example
+
+Consider this component:
+
+```typescript
+// Teams.tsx
+const Teams = (props) => {
+    const [data, { loading }] = useTeamsQuery({ variables: { orgName, pageSize: 10 } });
+    // rest of the business logic
+    return (
+        // component render Markup
+    )
+}
+```
+
+The generated `routes.json` structure will look like this:
+
+```json
+{
+    "queries": {
+        "TeamsDocument": "{orgName: params.orgName, pageSize: 10}"
+    }
+}
+```
+
+## Generated Loaders
+
+The generator function uses this meta-information to create loaders for both server and client:
+
+```typescript
+export const loaders = ({ params, context }) => {
+    const { apolloClient: client } = context;
+    const queries = { GetTeamsDocument: { orgName: params.orgName, pageSize: 10 } };
+
+    const organizationTeamsQuery = client.query({
+        query: GetTeamsDocument,
+        variables: queries['GetTeamsDocument'],
+        fetchPolicy: __SERVER__ ? 'network-only' : 'cache-first',
+    });
+
+    return {
+        data: {
+            organizationTeamsQuery,
+        },
+    };
+};
+
+const clientLoader = async ({ params, serverLoader }) => {
+    const client = window.__APOLLO_CLIENT__;
+    try {
+        const getKey = (documentName) => camelCase(documentName).replace('Document', '');
+        const queries = { GetTeamsDocument: { orgName: params.orgName, pageSize: 10 } };
+        const queryKeys = ['TeamsQuery'];
+        let shouldCallServerLoader = false;
+        let response = {};
+        let cachedData, cacheKey;
+
+        cachedData = client.cache.readQuery({
+            query: GetTeamsDocument,
+            variables: queries['GetTeamsDocument'],
+        });
+        cacheKey = getKey('GetTeamsDocument');
+
+        if (!cachedData) {
+            shouldCallServerLoader = true;
+        }
+        if (cachedData && cachedData[cacheKey]) {
+            response[queryKeys[0]] = Promise.resolve(cachedData[cacheKey]);
+        }
+
+        if (!shouldCallServerLoader) return response;
+        const serverData = await serverLoader();
+        let queryKey = queryKeys[0];
+
+        if (!serverData[queryKey].then) {
+            return;
+        }
+        serverData[queryKey].then(({ data }) => {
+            client.cache.writeQuery({
+                query: GetTeamsDocument,
+                variables: queries['GetTeamsDocument'],
+                data,
+            });
+        });
+
+        return serverData;
+    } catch (err) {
+        console.error('Error in clientLoader', err);
+    }
+};
+```
+
+This approach ensures that by the time the component requests the data, it is already available in the Apollo Cache, reducing redundancy and improving performance.
+
+## Related Topics
+
+- For detailed parameter generation, see [Query Params Generator](query-params-generator.md)
+- For automated loader generation, see [Generated Data Loaders](generated-data-loaders.md)
+- For authentication integration, see [Authentication and Authorization](routes-json-auth.md)
+
+[Back to Index](routes-json-index.md) | [Previous: Advanced Configurations](routes-json-advanced.md) | [Next: Query Parameters Generator](query-params-generator.md)

package/lib/templates/content/docs/remix/configuration/generated-resource-loaders.md

@@ -0,0 +1,257 @@
+---
+meta:
+    title: Generated Resource Loaders
+    description: Generated Resource Loaders
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Generated Resource Loaders...
+headers:
+    Cache-Control: no-cache
+---
+
+# Resource Routes in Generated Data Loaders
+
+## Resource Routes Overview
+
+Resource routes are special routes that require resolved data rather than deferred promises. They are commonly used for API endpoints, data fetching routes, and other scenarios where immediate data resolution is required.
+
+## Configuration
+
+### routes.json Configuration
+
+```json
+{
+    "/api/teams": {
+        "isResourceRoute": true,
+        "resourceUri": "teams",
+        "queries": {
+            "GetTeamsDocument": "{orgName: params.orgName}"
+        },
+        "middlewares": ["@your-package/middleware/configurations"]
+    }
+}
+```
+
+### GraphQL Query Definition
+
+```graphql
+query GetTeams($orgName: String!) {
+    teams(orgName: $orgName) {
+        id
+        name
+        members {
+            id
+            name
+            role
+        }
+        settings {
+            isPublic
+            allowInvites
+        }
+    }
+}
+```
+
+## Generated Loader
+
+```typescript
+import { json } from '@remix-run/node';
+import { GetTeamsDocument } from './graphql/teams.generated';
+
+export const loader = async ({ context, params }) => {
+    const loaderErrors = [];
+    let defaultLoaderData = {};
+
+    // Configuration middleware
+    const middlewareStack = [];
+    const { apolloClient: client } = context;
+
+    try {
+        // Execute queries with immediate resolution
+        const teamsResult = await client.query({
+            query: GetTeamsDocument,
+            variables: { orgName: params.orgName },
+            fetchPolicy: 'network-only',
+        });
+
+        defaultLoaderData = {
+            teams: teamsResult.data.teams,
+        };
+
+        // Execute middleware if configured
+        if (options.resourceUri) {
+            const { configurations } = await executeConfigurationMiddleware(params);
+            defaultLoaderData.configurations = configurations;
+        }
+
+        return json({
+            ...defaultLoaderData,
+            errors: loaderErrors,
+        });
+    } catch (error) {
+        loaderErrors.push(error);
+        return json({ errors: loaderErrors }, { status: 500 });
+    }
+};
+```
+
+## Example Usage
+
+### Resource Route Component
+
+```typescript
+// app/routes/api/teams.ts
+import { useLoaderData } from '@remix-run/react';
+import type { Team } from '~/types';
+
+interface LoaderData {
+    teams: Team[];
+    configurations?: {
+        maxTeamSize: number;
+        features: string[];
+    };
+    errors?: Array<{ message: string }>;
+}
+
+export default function TeamsResource() {
+    const { teams, configurations, errors } = useLoaderData<LoaderData>();
+
+    if (errors?.length) {
+        return json(
+            {
+                error: 'Failed to load teams data',
+                details: errors,
+            },
+            {
+                status: 500,
+            },
+        );
+    }
+
+    return json({
+        teams,
+        settings: configurations,
+        timestamp: new Date().toISOString(),
+    });
+}
+```
+
+### Consuming Component
+
+```typescript
+// app/routes/teams/index.tsx
+import { useEffect, useState } from 'react';
+
+export default function TeamsPage() {
+    const [teams, setTeams] = useState<Team[]>([]);
+    const [loading, setLoading] = useState(true);
+
+    useEffect(() => {
+        async function fetchTeams() {
+            try {
+                const response = await fetch('/api/teams?orgName=acme');
+                const data = await response.json();
+                setTeams(data.teams);
+            } catch (error) {
+                console.error('Failed to fetch teams:', error);
+            } finally {
+                setLoading(false);
+            }
+        }
+
+        fetchTeams();
+    }, []);
+
+    if (loading) return <div>Loading teams...</div>;
+
+    return (
+        <div>
+            <h1>Teams</h1>
+            <div className="teams-grid">
+                {teams.map((team) => (
+                    <TeamCard key={team.id} team={team} maxSize={data.configurations?.maxTeamSize} />
+                ))}
+            </div>
+        </div>
+    );
+}
+
+// TeamCard component
+const TeamCard = ({ team, maxSize }) => (
+    <div className="team-card">
+        <h3>{team.name}</h3>
+        <div className="member-count">
+            Members: {team.members.length} / {maxSize}
+        </div>
+        <div className="member-list">
+            {team.members.map((member) => (
+                <div key={member.id} className="member">
+                    {member.name} ({member.role})
+                </div>
+            ))}
+        </div>
+        <div className="team-settings">
+            {team.settings.isPublic ? 'Public' : 'Private'} Team
+            {team.settings.allowInvites && ' • Invites Enabled'}
+        </div>
+    </div>
+);
+```
+
+### Using with Forms
+
+```typescript
+// app/routes/teams/new.tsx
+import { Form, useActionData } from '@remix-run/react';
+
+export default function NewTeam() {
+    const actionData = useActionData();
+
+    return (
+        <Form method="post" action="/api/teams">
+            <div>
+                <label htmlFor="teamName">Team Name:</label>
+                <input id="teamName" name="teamName" type="text" required />
+            </div>
+            <div>
+                <label htmlFor="isPublic">
+                    <input id="isPublic" name="isPublic" type="checkbox" />
+                    Make team public
+                </label>
+            </div>
+            <button type="submit">Create Team</button>
+            {actionData?.errors && (
+                <div className="error">
+                    {actionData.errors.map((error) => (
+                        <p key={error.message}>{error.message}</p>
+                    ))}
+                </div>
+            )}
+        </Form>
+    );
+}
+```
+
+## Key Differences from Regular Routes
+
+1. **Data Resolution**
+    - All data is resolved before sending response
+    - Always returns `json` responses
+    - No streaming or deferred loading
+
+2. **Error Handling**
+    - Errors are collected and returned immediately
+    - Appropriate HTTP status codes are set
+    - Error details can be included in the response
+
+3. **Middleware Integration**
+    - Middleware executes synchronously
+    - All configurations are resolved before response
+    - Results are included in the JSON response
+
+4. **Response Format**
+    - Structured JSON responses
+    - Can include metadata and configurations
+    - Suitable for API consumption
+
+[Back to Index](routes-json-index.md) | [Previous: Query Parameters Generator](query-params-generator.md) | [Next: CSS Import and Stylesheets](css-import-and-stylesheets.md)