lovable-ssr 0.1.8 → 0.1.10

package/README.md

@@ -1,6 +1,6 @@
 # lovable-ssr
 
-SSR and route data engine for [Lovable](https://lovable.dev) projects. Provides a route registry (singleton), `getServerData`-based data loading for SSR and SPA navigation, and an Express + Vite server.
+SSR and route data engine for [Lovable](https://lovable.dev) projects: route registry, `getServerData`, Express + Vite server.
 
 **Documentation:** [Documentação completa](https://calm-meadow-5cf6.github-8c8.workers.dev/)
 
@@ -14,123 +14,11 @@ Peer dependencies: `react`, `react-dom`, `react-router-dom` (^18 / ^6).
 
 ## Quick start
 
-### 1. Register routes
+1. Register routes with `registerRoutes(routes)`.
+2. Wrap your app with `BrowserRouteDataProvider` and render `AppRoutes` (inside `BrowserRouter`).
+3. (Optional) SSR: entry module + `createServer` from `lovable-ssr/server`.
 
-Define your routes and call `registerRoutes` so the framework can match paths and run `getServerData`:
-
-```ts
-// src/routes.ts (or wherever you define routes)
-import { registerRoutes, type RouteConfig, type ComponentWithGetServerData } from 'lovable-ssr';
-import HomePage from '@/pages/HomePage';
-import VideoPage from '@/pages/VideoPage';
-
-export const routes: RouteConfig[] = [
-  { path: '/', Component: HomePage, isSSR: true },
-  { path: '/video/:id', Component: VideoPage, isSSR: true },
-  { path: '*', Component: NotFound, isSSR: false },
-];
-
-registerRoutes(routes);
-```
-
-### 2. App shell
-
-Ensure routes are loaded (so the registry is filled), then use `BrowserRouteDataProvider` and `AppRoutes`. The framework reads `window.__PRELOADED_DATA__` and the current pathname and fills the route data context for you (no need to declare `Window` or compute initial route/params in the app):
-
-```tsx
-// src/App.tsx
-import './routes'; // runs registerRoutes(routes)
-import { BrowserRouteDataProvider, AppRoutes } from 'lovable-ssr';
-import { BrowserRouter } from 'react-router-dom';
-
-export default function App() {
-  return (
-    <BrowserRouter>
-      <BrowserRouteDataProvider>
-        <AppRoutes />
-      </BrowserRouteDataProvider>
-    </BrowserRouter>
-  );
-}
-```
-
-The package augments `Window` with `__PRELOADED_DATA__?: Record<string, unknown>` so you don't need to declare it. If you prefer to wire `RouteDataProvider` yourself (e.g. for testing), use `RouterService`, `RouteDataProvider`, and the same initial data logic.
-
-### 3. SSR entry (optional)
-
-For SSR, add an entry module that registers routes and calls the framework’s `render` with your app wrappers (e.g. QueryClient, Toaster):
-
-```tsx
-// src/entry-server.tsx
-import { registerRoutes, render as frameworkRender } from 'lovable-ssr';
-import { routes } from '@/routes';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-
-registerRoutes(routes);
-
-export async function render(url: string) {
-  return frameworkRender(url, {
-    wrap: (children) => (
-      <QueryClientProvider client={new QueryClient()}>
-        {children}
-      </QueryClientProvider>
-    ),
-  });
-}
-```
-
-### 4. SSR server (optional)
-
-Run the Express + Vite server using the framework’s `createServer` (import from the `server` subpath so Node-only code is not bundled in the client). The server **preloads your entry module at startup** so `registerRoutes(routes)` runs and the route registry is filled before the first request; that way `isSsrRoute(pathname)` works correctly. You do **not** import the routes module in `server.ts` (that would pull React components into Node before Vite is ready and can cause “React is not defined” or similar).
-
-```ts
-// src/ssr/server.ts
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createServer } from 'lovable-ssr/server';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const root = path.resolve(__dirname, '../..');
-
-createServer({
-  root,
-  entryPath: 'src/ssr/entry-server.tsx',
-  port: process.env.PORT ? Number(process.env.PORT) : 5173,
-})
-  .then((s) => s.listen())
-  .catch(console.error);
-```
-
-Scripts:
-
-- **Dev SPA:** `vite`
-- **Dev SSR:** `tsx src/ssr/server.ts`
-- **Dev SSR with watch:** use `nodemon` to watch `src/ssr` and your app (e.g. `src/application` or `src/pages`); run with `NODE_OPTIONS=--inspect` and **Attach to Node** (port 9229, `restart: true`) so the server restarts on change and the debugger reconnects. See [SSR guide → Watch and debug](https://calm-meadow-5cf6.github-8c8.workers.dev/guide/ssr.html#_4-watch-and-debug-optional).
-- **Build SSR:** `vite build && vite build --ssr src/entry-server.tsx --outDir dist`
-- **Preview SSR:** `npm run build:ssr && NODE_ENV=production tsx src/ssr/server.ts`
-
-## API
-
-- **Types:** `RouteConfig`, `ComponentWithGetServerData`
-- **Registry:** `registerRoutes(routes)`, `getRoutes()`
-- **Router:** `RouterService.matchRoute(pathname)`, `RouterService.routeParams(path, pathname)`, `RouterService.isSsrRoute(pathname)`
-- **Data:** `RouteDataProvider`, `useRouteData()`, `buildRouteKey(path, params)`, `RouteDataState`, `InitialRouteShape`
-- **UI:** `AppRoutes` (no props), `BrowserRouteDataProvider` (wraps children with `RouteDataProvider` using `window.__PRELOADED_DATA__` and current pathname; use inside `BrowserRouter`)
-- **SSR:** `render(url, options?)` with `options.wrap = (children) => ReactNode`
-- **Server:** `createServer(config)` and `runServer(config?)` from `lovable-ssr/server`
-
-## Pages with `getServerData`
-
-Attach a `getServerData` function to the route component; it runs on the server for SSR and on the client when navigating to that route if data is not already cached (keyed by path + params).
-
-```ts
-async function getServerData(params?: Record<string, string>) {
-  const id = params?.id;
-  const data = await fetch(`/api/videos/${id}`).then((r) => r.json());
-  return { video: data };
-}
-VideoPage.getServerData = getServerData;
-```
+Details, examples, and API: see the [documentation](https://calm-meadow-5cf6.github-8c8.workers.dev/).
 
 ## License
 

package/dist/components/AppRoutes.js

@@ -17,7 +17,7 @@ export function AppRoutes() {
     const { data, setData } = useRouteData();
     const currentData = routeKey ? data[routeKey] : undefined;
     const getServerData = matchedRoute?.Component?.getServerData;
-    params.searchParams = RouterService.searchParams(pathname);
+    params.searchParams = RouterService.searchParams(location.search ?? '');
     useEffect(() => {
         if (!routeKey || !getServerData || currentData !== undefined)
             return;

package/dist/router/RouterService.d.ts

@@ -3,7 +3,8 @@ declare function matchPath(pathPattern: string, pathname: string): boolean;
 declare function isSsrRoute(pathname: string): boolean;
 declare function matchRoute(pathname: string): RouteConfig | undefined;
 declare function routeParams(routePath: string, pathname?: string): Record<'routeParams' | 'searchParams', Record<string, string>>;
-declare function searchParams(pathname: string): Record<string, string>;
+/** Parses the URL query string (e.g. "?filter=FPS" or "filter=FPS") into key/value pairs. */
+declare function searchParams(queryString: string): Record<string, string>;
 declare const RouterService: {
     isSsrRoute: typeof isSsrRoute;
     matchPath: typeof matchPath;

package/dist/router/RouterService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RouterService.d.ts","sourceRoot":"","sources":["../../src/router/RouterService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,iBAAS,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOjE;AAED,iBAAS,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG7C;AAED,iBAAS,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAM7D;AAED,iBAAS,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,aAAa,GAAG,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAazH;AACD,iBAAS,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAG9D;AAED,QAAA,MAAM,aAAa;;;;;;CAMlB,CAAC;AAEF,eAAe,aAAa,CAAC"}
+{"version":3,"file":"RouterService.d.ts","sourceRoot":"","sources":["../../src/router/RouterService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,iBAAS,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOjE;AAED,iBAAS,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG7C;AAED,iBAAS,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAM7D;AAED,iBAAS,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,aAAa,GAAG,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAazH;AACD,6FAA6F;AAC7F,iBAAS,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGjE;AAED,QAAA,MAAM,aAAa;;;;;;CAMlB,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/dist/router/RouterService.js

@@ -36,9 +36,10 @@ function routeParams(routePath, pathname) {
     });
     return params;
 }
-function searchParams(pathname) {
-    const searchParams = new URLSearchParams(pathname);
-    return Object.fromEntries(searchParams.entries());
+/** Parses the URL query string (e.g. "?filter=FPS" or "filter=FPS") into key/value pairs. */
+function searchParams(queryString) {
+    const parsed = new URLSearchParams(queryString);
+    return Object.fromEntries(parsed.entries());
 }
 const RouterService = {
     isSsrRoute,

package/dist/ssr/render.js

@@ -12,7 +12,7 @@ export async function render(url, options) {
         routeParams: {},
         searchParams: {},
     };
-    const searchParams = matchedRoute ? RouterService.searchParams(pathname) : {};
+    const searchParams = matchedRoute ? RouterService.searchParams(fullUrl.search) : {};
     params.searchParams = searchParams;
     let preloadedData = { is_success: true };
     const getServerData = matchedRoute?.Component?.getServerData;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lovable-ssr",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "SSR and route data engine for Lovable projects",
   "type": "module",
   "main": "./dist/index.js",