🔌Basics - syncRequest

The syncRequest function is used when you want to broadcast behavior across all users, such as real-time UI updates or collaborative triggers. It's similar in structure to apiRequest, but with a very different purpose.

Unlike apiRequest, syncRequest does not return any data and does not require async/await because it isnt a promise. You can safely call it directly in a React component.

---

📁 Example Structure

src/
    dashboard/
        page.tsx
        _components/
        _functions/
        _sync/
            refreshData_server.ts ← (optional) filters or modifies behavior
            refreshData_client.ts ← (required) runs on all users
    home/
        page.tsx

✅ The folder name must end in sync, such as _sync or _dashboardSync.

🚫 Sync routes are scoped to their route folder. In the example above, refreshData can be called only from /dashboard. It won't be available on /home or other pages.

💡We recommend starting folder names with an underscore (_) to indicate that it’s a non-route folder, making the project structure easier to read for other developers.

This structure allows you to use the same sync name in different places (e.g. refreshData on /dashboard and /home), without any conflict.

---

⚙️ How syncRequest Works

1. A user calls syncRequest({ name: "refreshData", data }) from their client.

2. The server checks if _sync/refreshData_server.ts exists.

   • If it exists, it runs this file for every user.

   • If the server file returns a truthy value, the corresponding _client.ts file runs for that user.

3. If no _server.ts file exists, the _client.ts file runs automatically for all users.

Server file receive an object that holds these values:

• data – the object passed from the triggering client

• user – includes user session info, token, and route location

• functions – backend utility helpers like database access

Client file receives an object that holds these values:

• clientData – the data object passed from the client

• serverData – the return value of the server

---

🧠 Purpose Breakdown

File Name	Runs For	Used For
*_server.ts	Every connected user	Filter out users who should not sync or perform a database action
*_client.ts	Users that passed server check	UI updates or local logic

---

🛑 Where You Can and Can't Call

• ✅ Can call syncRequest({ name: "refreshData", data }) from inside the page.tsx or components under the same route (e.g. /dashboard)

• ❌ Cannot call a sync route that belongs to a different page route (e.g., trying to call /home/_sync/refreshData from /dashboard)

---

✅ Summary

• Use syncRequest to sync UI and behavior across users

• Requires a _sync folder, scoped per route

• Call it anywhere in your React components – no async await needed

• In most cases the server file acts as a filter, client file handles the reaction