(docs) Request for elaboration on usage docs for defineEntries

[tylersayshi]

defineEntries is a fn call to define how to render, build, and configure the ssr for your waku app.

Some initial usage docs live here: https://github.com/dai-shi/waku/blob/main/docs/minimal-api.mdx

It would be really helpful for someone new to look through how the initial usages of defineEntries are used, then summarize some info in a docs entry for this function.

[ojj1123]

I was wondering if you could explain where it is the explanation of defineEntries function in Docs or README! I couldn't find it since waku was released as v0.19.0. Is it deprecated

#24 (comment)

Oh I was also wondered defineEntries before releasing managed mode. If it's important to know this API for library authors, it's good to describe this API. Reading the source code of it briefly, It feels like it's working for build process. But it's too hard for newcomers to know about it.

waku/packages/waku/src/lib/builder/build.ts

Line 750 in 901594c

const distEntries = await import(filePathToFileURL(distEntriesFile));

How about explain API descriptions like what each parameter work for or the interaction of parameters(renderEntries, getBuildConfig, getSsrConfig)? And then I feel like that it's easier to know and investigate the use cases of this API.

[rmarscher]

I saw that new_defineEntries() is now available.

• https://github.com/dai-shi/waku/blob/main/examples/31_minimal/src/entries.tsx
• https://github.com/dai-shi/waku/blob/v0.21.6/packages/waku/src/minimal/server.ts#L64-L114

[dai-shi]

We are in the middle of refactoring. defineEntries will be replaced with new_defineEntries soon-ish.

[dai-shi]

@tylersayshi I'm not sure if this is a good first issue anymore.

[rmarscher]

docs/minimal-api.mdx

To use React Server Components in Waku, you need to create an entries.tsx file in the project root directory and defineEntries to handle server requests.

If src/entries.tsx does not exist, the default uses the fsRouter from 'waku/router/server'. fsRouter returns a call to defineRouter which return a call to defineEntries.

handleRequest is passed an input object which contains the request as well as properties that vary depending on the "type" property. The possible "type" values on the input object are 'component', 'function', 'action' and 'custom'.

'component' is a server component render request. It is passed the rscPath and the rscParams.

'function' is a request to call a server function. It is passed the function args and it is passed the server function to call.

'action' --- I am not exactly sure what this is... but I think is it to render the HTML response via SSR after calling a server function that is part of a form action. If SSR (server-side rendering of HTML) is disabled, this returns null.

'custom' is a request to render HTML via SSR. If SSR is disabled, this returns null. A fallback HTML response must be provided for initial requests when SSR is disabled.

import { defineConfig } from 'waku/config';

export default defineConfig({
  middleware: () => [
    // context, dev-server and handler are the default middleware if not defined
    import('waku/middleware/context'),
    import('waku/middleware/dev-server'),
    import('waku/middleware/handler'),
    // fallback required if SSR is not enabled
    import('waku/middleware/fallback'),
  ],
});

The default handlers used by the router can be found in waku/router/define-router.

examples/12_nossr/src/entries.ts shows how it is possible to use defineEntries as middleware around the default fsRouter.

[dai-shi]

Nice! Feel free to send a PR please.

I'm not sure if we should write about "router" and "managed mode" in minimal-api docs. Should there be another doc?

[rmarscher]

Nice! Feel free to send a PR please.

👍 I am backlogged, but I will get around it.

I'm not sure if we should write about "router" and "managed mode" in minimal-api docs. Should there be another doc?

Good idea to have another doc for managed mode and the filesystem router. The minimal-api docs can point out that managed mode is the default behavior and link to the other doc that explains.