@softr/sdk 0.0.53 → 0.0.54
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/auth/isomorphic.d.ts +1 -1
- package/dist/auth/isomorphic.js +2 -1
- package/dist/boot-error.js +1 -0
- package/dist/default-error-overlay.d.ts +2 -2
- package/dist/index.d.ts +2 -1
- package/dist/index.js +2 -1
- package/dist/mcp.d.ts +2 -2
- package/dist/package.js +1 -1
- package/dist/pwa.d.ts +54 -0
- package/dist/pwa.js +152 -0
- package/package.json +1 -1
- package/skills/softr-sdk/SKILL.md +6 -2
- package/skills/softr-sdk/auth/SKILL.md +1 -1
- package/skills/softr-sdk/charts-and-metrics/SKILL.md +1 -1
- package/skills/softr-sdk/current-user/SKILL.md +1 -1
- package/skills/softr-sdk/file-uploads/SKILL.md +1 -1
- package/skills/softr-sdk/integrations/SKILL.md +1 -1
- package/skills/softr-sdk/mcp/SKILL.md +1 -1
- package/skills/softr-sdk/pwa/SKILL.md +77 -0
- package/skills/softr-sdk/record-mutations/SKILL.md +1 -1
- package/skills/softr-sdk/record-queries/SKILL.md +2 -2
- package/skills/softr-sdk/region-visibility/SKILL.md +1 -1
- package/skills/softr-sdk/routes-and-visibility/SKILL.md +1 -1
- package/skills/softr-sdk/workflows/SKILL.md +1 -1
|
@@ -17,7 +17,7 @@ import * as _tanstack_react_start0 from "@tanstack/react-start";
|
|
|
17
17
|
* requestMiddleware: [softrAuthMiddleware()],
|
|
18
18
|
* }))
|
|
19
19
|
*/
|
|
20
|
-
declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
|
|
20
|
+
declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
|
|
21
21
|
user: User | null;
|
|
22
22
|
permissions: Permissions;
|
|
23
23
|
}>;
|
package/dist/auth/isomorphic.js
CHANGED
|
@@ -4,6 +4,7 @@ import { sessionConfig } from "./config.js";
|
|
|
4
4
|
import { clearSession, makeSessionDataCookie, readSessionData, readSessionToken } from "./session.js";
|
|
5
5
|
import { makePlatform } from "./platform.js";
|
|
6
6
|
import { bootErrorMiddleware } from "../boot-error.js";
|
|
7
|
+
import { pwaMiddleware } from "../pwa.js";
|
|
7
8
|
import { createMiddleware, createServerFn, getGlobalStartContext } from "@tanstack/react-start";
|
|
8
9
|
import { rootRouteId, useRouteContext } from "@tanstack/react-router";
|
|
9
10
|
|
|
@@ -21,7 +22,7 @@ import { rootRouteId, useRouteContext } from "@tanstack/react-router";
|
|
|
21
22
|
* }))
|
|
22
23
|
*/
|
|
23
24
|
function softrAuthMiddleware() {
|
|
24
|
-
return createMiddleware({ type: "request" }).middleware([bootErrorMiddleware()]).server(async ({ next }) => {
|
|
25
|
+
return createMiddleware({ type: "request" }).middleware([bootErrorMiddleware(), pwaMiddleware()]).server(async ({ next }) => {
|
|
25
26
|
async function getSession() {
|
|
26
27
|
const token = readSessionToken();
|
|
27
28
|
const cached = readSessionData(token);
|
package/dist/boot-error.js
CHANGED
|
@@ -16,6 +16,7 @@ function bootErrorMiddleware() {
|
|
|
16
16
|
return await next();
|
|
17
17
|
} catch (error) {
|
|
18
18
|
if (handlerType === "serverFn" || error instanceof Response || isRedirect(error) || isNotFound(error)) throw error;
|
|
19
|
+
console.error("[@softr/sdk] boot error:", error);
|
|
19
20
|
return new Response(errorPage(error), {
|
|
20
21
|
status: 500,
|
|
21
22
|
headers: { "content-type": "text/html; charset=utf-8" }
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import * as
|
|
1
|
+
import * as react1 from "react";
|
|
2
2
|
|
|
3
3
|
//#region src/default-error-overlay.d.ts
|
|
4
4
|
type Props = {
|
|
@@ -8,6 +8,6 @@ type Props = {
|
|
|
8
8
|
declare function DefaultErrorOverlay({
|
|
9
9
|
error,
|
|
10
10
|
reset
|
|
11
|
-
}: Props):
|
|
11
|
+
}: Props): react1.JSX.Element;
|
|
12
12
|
//#endregion
|
|
13
13
|
export { DefaultErrorOverlay };
|
package/dist/index.d.ts
CHANGED
|
@@ -8,6 +8,7 @@ import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedErr
|
|
|
8
8
|
import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
|
|
9
9
|
import { softrMcpMiddleware } from "./mcp.js";
|
|
10
10
|
import { useUserTimezone } from "./timezone.js";
|
|
11
|
+
import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
|
|
11
12
|
import { DefaultErrorOverlay } from "./default-error-overlay.js";
|
|
12
13
|
import { Audience } from "./visibility/audience.js";
|
|
13
|
-
export { type ActionPermissions, Audience, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };
|
|
14
|
+
export { type ActionPermissions, Audience, DefaultErrorOverlay, type FileAttachment, type FileItem, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePwaInstall, useUserTimezone };
|
package/dist/index.js
CHANGED
|
@@ -2,10 +2,11 @@ import { useFileUpload } from "./core/use-file-upload.js";
|
|
|
2
2
|
import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
|
|
3
3
|
import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
|
|
4
4
|
import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
|
|
5
|
+
import { SoftrPwaHead, usePwaInstall } from "./pwa.js";
|
|
5
6
|
import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
|
|
6
7
|
import { softrMcpMiddleware } from "./mcp.js";
|
|
7
8
|
import { useUserTimezone } from "./timezone.js";
|
|
8
9
|
import { DefaultErrorOverlay } from "./default-error-overlay.js";
|
|
9
10
|
import { Audience } from "./visibility/audience.js";
|
|
10
11
|
|
|
11
|
-
export { Audience, DefaultErrorOverlay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };
|
|
12
|
+
export { Audience, DefaultErrorOverlay, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePwaInstall, useUserTimezone };
|
package/dist/mcp.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { DatasourceAction } from "./action.js";
|
|
2
|
-
import * as
|
|
2
|
+
import * as _tanstack_react_start3 from "@tanstack/react-start";
|
|
3
3
|
|
|
4
4
|
//#region src/mcp.d.ts
|
|
5
5
|
|
|
@@ -37,6 +37,6 @@ type SoftrMcpOptions = {
|
|
|
37
37
|
* ],
|
|
38
38
|
* }))
|
|
39
39
|
*/
|
|
40
|
-
declare function softrMcpMiddleware(options?: SoftrMcpOptions):
|
|
40
|
+
declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start3.RequestMiddlewareAfterServer<{}, undefined, undefined>;
|
|
41
41
|
//#endregion
|
|
42
42
|
export { softrMcpMiddleware };
|
package/dist/package.js
CHANGED
package/dist/pwa.d.ts
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import * as react0 from "react";
|
|
2
|
+
import "@tanstack/react-start";
|
|
3
|
+
|
|
4
|
+
//#region src/pwa.d.ts
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The links that make the app installable: its manifest and its home screen
|
|
8
|
+
* icon. Render it once, in `<head>` in the root route's `RootDocument`.
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* function RootDocument({ children }: { children: React.ReactNode }) {
|
|
12
|
+
* return (
|
|
13
|
+
* <html lang="en">
|
|
14
|
+
* <head>
|
|
15
|
+
* <HeadContent />
|
|
16
|
+
* <SoftrPwaHead />
|
|
17
|
+
* </head>
|
|
18
|
+
* <body>
|
|
19
|
+
* {children}
|
|
20
|
+
* <Scripts />
|
|
21
|
+
* </body>
|
|
22
|
+
* </html>
|
|
23
|
+
* )
|
|
24
|
+
* }
|
|
25
|
+
*/
|
|
26
|
+
declare function SoftrPwaHead(): react0.FunctionComponentElement<react0.FragmentProps>;
|
|
27
|
+
type PwaPlatform = "ios" | "android" | "desktop";
|
|
28
|
+
type PwaInstall = {
|
|
29
|
+
available: false;
|
|
30
|
+
} | {
|
|
31
|
+
available: true;
|
|
32
|
+
/** Which steps install the app on this device. */
|
|
33
|
+
platform: PwaPlatform;
|
|
34
|
+
/** The name the home screen will show. */
|
|
35
|
+
name: string;
|
|
36
|
+
/** The icon the home screen will show. */
|
|
37
|
+
iconUrl: string;
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* Whether to offer installing the app, and on which platform. Render an
|
|
41
|
+
* install button only while this says `available`: it is unavailable while
|
|
42
|
+
* loading, when the builder has not turned the PWA on, when Softr has switched
|
|
43
|
+
* it off, and when the app already runs installed.
|
|
44
|
+
*
|
|
45
|
+
* @example
|
|
46
|
+
* function InstallButton() {
|
|
47
|
+
* const install = usePwaInstall()
|
|
48
|
+
* if (!install.available) return null
|
|
49
|
+
* return <button onClick={() => openSteps(install.platform)}>Install {install.name}</button>
|
|
50
|
+
* }
|
|
51
|
+
*/
|
|
52
|
+
declare function usePwaInstall(): PwaInstall;
|
|
53
|
+
//#endregion
|
|
54
|
+
export { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall };
|
package/dist/pwa.js
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
import { logger } from "./logger.js";
|
|
2
|
+
import { fetch } from "./fetch.js";
|
|
3
|
+
import { sessionConfig } from "./auth/config.js";
|
|
4
|
+
import { platformApiUrl } from "./auth/platform.js";
|
|
5
|
+
import { Fragment, createElement, useEffect, useState } from "react";
|
|
6
|
+
import { createMiddleware } from "@tanstack/react-start";
|
|
7
|
+
import { z } from "zod";
|
|
8
|
+
|
|
9
|
+
//#region src/pwa.ts
|
|
10
|
+
const MANIFEST_PATH = "/manifest.webmanifest";
|
|
11
|
+
const ICON_PATH = "/apple-touch-icon.png";
|
|
12
|
+
const INSTALL_PATH = "/_softr/pwa.json";
|
|
13
|
+
const TTL_MS = 6e4;
|
|
14
|
+
const CACHE_CONTROL = "public, max-age=60";
|
|
15
|
+
const pwaSchema = z.object({
|
|
16
|
+
manifest: z.record(z.string(), z.unknown()),
|
|
17
|
+
install: z.object({
|
|
18
|
+
name: z.string(),
|
|
19
|
+
iconUrl: z.string()
|
|
20
|
+
})
|
|
21
|
+
});
|
|
22
|
+
let cached;
|
|
23
|
+
/**
|
|
24
|
+
* The app's PWA, or `null` when it is not installable right now. Never
|
|
25
|
+
* rejects: a failure reads as not installable and is not remembered, so the
|
|
26
|
+
* next request tries again.
|
|
27
|
+
*/
|
|
28
|
+
function readPwa() {
|
|
29
|
+
const now = Date.now();
|
|
30
|
+
if (cached !== void 0 && cached.expires > now) return cached.pwa;
|
|
31
|
+
const entry = {
|
|
32
|
+
expires: now + TTL_MS,
|
|
33
|
+
pwa: fetchPwa().catch((error) => {
|
|
34
|
+
logger.warn("Could not read the PWA settings:", error);
|
|
35
|
+
if (cached === entry) cached = void 0;
|
|
36
|
+
return null;
|
|
37
|
+
})
|
|
38
|
+
};
|
|
39
|
+
cached = entry;
|
|
40
|
+
return entry.pwa;
|
|
41
|
+
}
|
|
42
|
+
async function fetchPwa() {
|
|
43
|
+
const { applicationId } = sessionConfig();
|
|
44
|
+
const response = await fetch(`${await platformApiUrl()}/v1/vibe/applications/${applicationId}/pwa`, { headers: { accept: "application/json" } });
|
|
45
|
+
if (response.status === 404) return null;
|
|
46
|
+
if (!response.ok) throw new Error(`The platform answered ${response.status}`);
|
|
47
|
+
return pwaSchema.parse(await response.json());
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Serves the app's web app manifest, its home screen icon, and what an install
|
|
51
|
+
* button needs to know, from the app's own origin. Every other request passes
|
|
52
|
+
* through untouched.
|
|
53
|
+
*
|
|
54
|
+
* Answers 404, never an error page, when the app is not installable: a browser
|
|
55
|
+
* silently drops a manifest it cannot parse, so a 500 there would be invisible.
|
|
56
|
+
*/
|
|
57
|
+
function pwaMiddleware() {
|
|
58
|
+
return createMiddleware({ type: "request" }).server(async ({ next, pathname }) => {
|
|
59
|
+
if (pathname !== MANIFEST_PATH && pathname !== ICON_PATH && pathname !== INSTALL_PATH) return next();
|
|
60
|
+
const pwa = await readPwa();
|
|
61
|
+
if (pwa === null) return new Response(null, { status: 404 });
|
|
62
|
+
if (pathname === MANIFEST_PATH) return new Response(JSON.stringify(pwa.manifest), { headers: {
|
|
63
|
+
"content-type": "application/manifest+json",
|
|
64
|
+
"cache-control": CACHE_CONTROL
|
|
65
|
+
} });
|
|
66
|
+
if (pathname === INSTALL_PATH) return Response.json(pwa.install, { headers: { "cache-control": CACHE_CONTROL } });
|
|
67
|
+
try {
|
|
68
|
+
const iconResponse = await fetch(pwa.install.iconUrl);
|
|
69
|
+
if (!iconResponse.ok) return new Response(null, { status: 404 });
|
|
70
|
+
return new Response(iconResponse.body, { headers: {
|
|
71
|
+
"content-type": "image/png",
|
|
72
|
+
"cache-control": CACHE_CONTROL
|
|
73
|
+
} });
|
|
74
|
+
} catch (error) {
|
|
75
|
+
logger.warn("Could not fetch the PWA icon:", error);
|
|
76
|
+
return new Response(null, { status: 404 });
|
|
77
|
+
}
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* The links that make the app installable: its manifest and its home screen
|
|
82
|
+
* icon. Render it once, in `<head>` in the root route's `RootDocument`.
|
|
83
|
+
*
|
|
84
|
+
* @example
|
|
85
|
+
* function RootDocument({ children }: { children: React.ReactNode }) {
|
|
86
|
+
* return (
|
|
87
|
+
* <html lang="en">
|
|
88
|
+
* <head>
|
|
89
|
+
* <HeadContent />
|
|
90
|
+
* <SoftrPwaHead />
|
|
91
|
+
* </head>
|
|
92
|
+
* <body>
|
|
93
|
+
* {children}
|
|
94
|
+
* <Scripts />
|
|
95
|
+
* </body>
|
|
96
|
+
* </html>
|
|
97
|
+
* )
|
|
98
|
+
* }
|
|
99
|
+
*/
|
|
100
|
+
function SoftrPwaHead() {
|
|
101
|
+
return createElement(Fragment, null, createElement("link", {
|
|
102
|
+
rel: "manifest",
|
|
103
|
+
href: MANIFEST_PATH
|
|
104
|
+
}), createElement("link", {
|
|
105
|
+
rel: "apple-touch-icon",
|
|
106
|
+
href: ICON_PATH
|
|
107
|
+
}));
|
|
108
|
+
}
|
|
109
|
+
const installSchema = pwaSchema.shape.install;
|
|
110
|
+
/**
|
|
111
|
+
* Whether to offer installing the app, and on which platform. Render an
|
|
112
|
+
* install button only while this says `available`: it is unavailable while
|
|
113
|
+
* loading, when the builder has not turned the PWA on, when Softr has switched
|
|
114
|
+
* it off, and when the app already runs installed.
|
|
115
|
+
*
|
|
116
|
+
* @example
|
|
117
|
+
* function InstallButton() {
|
|
118
|
+
* const install = usePwaInstall()
|
|
119
|
+
* if (!install.available) return null
|
|
120
|
+
* return <button onClick={() => openSteps(install.platform)}>Install {install.name}</button>
|
|
121
|
+
* }
|
|
122
|
+
*/
|
|
123
|
+
function usePwaInstall() {
|
|
124
|
+
const [install, setInstall] = useState({ available: false });
|
|
125
|
+
useEffect(() => {
|
|
126
|
+
if (window.matchMedia("(display-mode: standalone)").matches || "standalone" in navigator && navigator.standalone === true) return;
|
|
127
|
+
let cancelled = false;
|
|
128
|
+
fetch(INSTALL_PATH, { headers: { accept: "application/json" } }).then(async (response) => {
|
|
129
|
+
if (!response.ok) return;
|
|
130
|
+
const parsed = installSchema.safeParse(await response.json());
|
|
131
|
+
if (!parsed.success || cancelled) return;
|
|
132
|
+
setInstall({
|
|
133
|
+
available: true,
|
|
134
|
+
platform: detectPlatform(),
|
|
135
|
+
...parsed.data
|
|
136
|
+
});
|
|
137
|
+
}).catch(() => {});
|
|
138
|
+
return () => {
|
|
139
|
+
cancelled = true;
|
|
140
|
+
};
|
|
141
|
+
}, []);
|
|
142
|
+
return install;
|
|
143
|
+
}
|
|
144
|
+
function detectPlatform() {
|
|
145
|
+
const userAgent = navigator.userAgent;
|
|
146
|
+
if (/iPhone|iPad|iPod/.test(userAgent) || /Macintosh/.test(userAgent) && navigator.maxTouchPoints > 1) return "ios";
|
|
147
|
+
if (/Android/.test(userAgent)) return "android";
|
|
148
|
+
return "desktop";
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
//#endregion
|
|
152
|
+
export { SoftrPwaHead, pwaMiddleware, usePwaInstall };
|
package/package.json
CHANGED
|
@@ -11,7 +11,7 @@ description: >-
|
|
|
11
11
|
metadata:
|
|
12
12
|
type: core
|
|
13
13
|
library: softr-sdk
|
|
14
|
-
library_version: 0.0.
|
|
14
|
+
library_version: 0.0.54
|
|
15
15
|
---
|
|
16
16
|
|
|
17
17
|
# Softr SDK core
|
|
@@ -29,7 +29,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
|
|
|
29
29
|
|
|
30
30
|
| Import | Runs | Holds |
|
|
31
31
|
| --- | --- | --- |
|
|
32
|
-
| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
|
|
32
|
+
| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
|
|
33
33
|
| `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
|
|
34
34
|
| `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
|
|
35
35
|
| `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
|
|
@@ -48,6 +48,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
|
|
|
48
48
|
| Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
|
|
49
49
|
| Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/SKILL.md) |
|
|
50
50
|
| Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
|
|
51
|
+
| Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
|
|
51
52
|
|
|
52
53
|
## Quick Decision Tree
|
|
53
54
|
|
|
@@ -82,6 +83,9 @@ Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)
|
|
|
82
83
|
Opening the app to an AI assistant over MCP?
|
|
83
84
|
load softr-sdk/mcp
|
|
84
85
|
|
|
86
|
+
Adding an install button, or making the app installable?
|
|
87
|
+
load softr-sdk/pwa
|
|
88
|
+
|
|
85
89
|
Writing a server function, loader, or middleware in general?
|
|
86
90
|
not a Softr concern. Use the TanStack Start skills.
|
|
87
91
|
```
|
|
@@ -16,7 +16,7 @@ description: >-
|
|
|
16
16
|
metadata:
|
|
17
17
|
type: sub-skill
|
|
18
18
|
library: softr-sdk
|
|
19
|
-
library_version: 0.0.
|
|
19
|
+
library_version: 0.0.54
|
|
20
20
|
---
|
|
21
21
|
|
|
22
22
|
**Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.
|
|
@@ -12,7 +12,7 @@ description: >-
|
|
|
12
12
|
metadata:
|
|
13
13
|
type: sub-skill
|
|
14
14
|
library: softr-sdk
|
|
15
|
-
library_version: 0.0.
|
|
15
|
+
library_version: 0.0.54
|
|
16
16
|
---
|
|
17
17
|
|
|
18
18
|
**Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
|
|
@@ -10,7 +10,7 @@ description: >-
|
|
|
10
10
|
metadata:
|
|
11
11
|
type: sub-skill
|
|
12
12
|
library: softr-sdk
|
|
13
|
-
library_version: 0.0.
|
|
13
|
+
library_version: 0.0.54
|
|
14
14
|
---
|
|
15
15
|
|
|
16
16
|
**Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.
|
|
@@ -10,7 +10,7 @@ description: >-
|
|
|
10
10
|
metadata:
|
|
11
11
|
type: sub-skill
|
|
12
12
|
library: softr-sdk
|
|
13
|
-
library_version: 0.0.
|
|
13
|
+
library_version: 0.0.54
|
|
14
14
|
---
|
|
15
15
|
|
|
16
16
|
**Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.
|
|
@@ -9,7 +9,7 @@ description: >-
|
|
|
9
9
|
metadata:
|
|
10
10
|
type: sub-skill
|
|
11
11
|
library: softr-sdk
|
|
12
|
-
library_version: 0.0.
|
|
12
|
+
library_version: 0.0.54
|
|
13
13
|
---
|
|
14
14
|
|
|
15
15
|
**Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pwa
|
|
3
|
+
description: >-
|
|
4
|
+
Let visitors install the app on their home screen: SoftrPwaHead for the
|
|
5
|
+
manifest and icon links, usePwaInstall to decide whether to show an install
|
|
6
|
+
button and which platform's steps to show, the PwaInstall and PwaPlatform
|
|
7
|
+
types, and how to check that the app is installable. The manifest and icon
|
|
8
|
+
are already served; never write them.
|
|
9
|
+
metadata:
|
|
10
|
+
type: sub-skill
|
|
11
|
+
library: softr-sdk
|
|
12
|
+
library_version: 0.0.54
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# Installing the app
|
|
16
|
+
|
|
17
|
+
The builder turns installing on in Studio, under Settings → Mobile app, and sets the name, colour and icon there. The app already answers with its manifest and icon once they do. What the app adds is two things: the links that point the browser at them, and a button that tells visitors how to install.
|
|
18
|
+
|
|
19
|
+
> **CRITICAL**: Never write a web app manifest, icon files, a service worker, or `manifest` / `apple-touch-icon` links of your own, in `public/` or in `head()`. The app already serves them from Studio's settings, and a file of your own shadows those settings.
|
|
20
|
+
> **CRITICAL**: Render an install button only while `usePwaInstall()` returns `available: true`. Never show it unconditionally, never cache the answer, never replace the check with your own. Softr can switch installing off for an app, and this check is the only way that reaches the button.
|
|
21
|
+
|
|
22
|
+
## Setup
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { SoftrPwaHead, usePwaInstall } from '@softr/sdk'
|
|
26
|
+
import type { PwaInstall, PwaPlatform } from '@softr/sdk'
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
type PwaPlatform = 'ios' | 'android' | 'desktop'
|
|
31
|
+
|
|
32
|
+
type PwaInstall =
|
|
33
|
+
| { available: false }
|
|
34
|
+
| {
|
|
35
|
+
available: true
|
|
36
|
+
platform: PwaPlatform // which steps install the app on this device
|
|
37
|
+
name: string // what the home screen will show
|
|
38
|
+
iconUrl: string // the icon the home screen will show
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Is the app installable?
|
|
43
|
+
|
|
44
|
+
The builder switches installing on in Studio, and `usePwaInstall()` reads that switch at runtime. To check it before writing any code, ask the running app for `/_softr/pwa.json`: `200` means installable, `404` means installing is off or there is no icon yet. Do not build an install button against a `404`: installing has to be turned on first. A change in Studio can take up to two minutes to reach the app.
|
|
45
|
+
|
|
46
|
+
## Core Patterns
|
|
47
|
+
|
|
48
|
+
### The links: `<SoftrPwaHead />`
|
|
49
|
+
|
|
50
|
+
Render it once, in `<head>` next to `<HeadContent />`, in `RootDocument` in `src/routes/__root.tsx`.
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
function RootDocument({ children }: { children: React.ReactNode }) {
|
|
54
|
+
return (
|
|
55
|
+
<html lang="en">
|
|
56
|
+
<head>
|
|
57
|
+
<HeadContent />
|
|
58
|
+
<SoftrPwaHead />
|
|
59
|
+
</head>
|
|
60
|
+
<body>
|
|
61
|
+
{children}
|
|
62
|
+
<Scripts />
|
|
63
|
+
</body>
|
|
64
|
+
</html>
|
|
65
|
+
)
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Whether to show a button: `usePwaInstall()`
|
|
70
|
+
|
|
71
|
+
It fetches after mount, so the first render, the server render included, always says `available: false`. It stays unavailable when the app is not installable, when the request fails, and when the app already runs installed from the home screen. Inside the Studio preview it says available, so the builder can see the button; installing itself only works on the published app.
|
|
72
|
+
|
|
73
|
+
There is no `install()` to call. No browser opens its install dialog for this app on request, so the button opens steps for `platform` instead: Share, then Add to Home Screen on iOS; the browser menu's Install app on Android and desktop. `name` and `iconUrl` tell the visitor what they are adding.
|
|
74
|
+
|
|
75
|
+
## References
|
|
76
|
+
|
|
77
|
+
- [SKILL.md](../SKILL.md): the entrypoints and which one each export lives on
|
|
@@ -11,7 +11,7 @@ description: >-
|
|
|
11
11
|
metadata:
|
|
12
12
|
type: sub-skill
|
|
13
13
|
library: softr-sdk
|
|
14
|
-
library_version: 0.0.
|
|
14
|
+
library_version: 0.0.54
|
|
15
15
|
---
|
|
16
16
|
|
|
17
17
|
**Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.
|
|
@@ -13,10 +13,10 @@ description: >-
|
|
|
13
13
|
metadata:
|
|
14
14
|
type: sub-skill
|
|
15
15
|
library: softr-sdk
|
|
16
|
-
library_version: 0.0.
|
|
16
|
+
library_version: 0.0.54
|
|
17
17
|
---
|
|
18
18
|
|
|
19
|
-
**Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
|
|
19
|
+
**Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
|
|
20
20
|
|
|
21
21
|
# Reading records
|
|
22
22
|
|
|
@@ -9,7 +9,7 @@ description: >-
|
|
|
9
9
|
metadata:
|
|
10
10
|
type: sub-skill
|
|
11
11
|
library: softr-sdk
|
|
12
|
-
library_version: 0.0.
|
|
12
|
+
library_version: 0.0.54
|
|
13
13
|
---
|
|
14
14
|
|
|
15
15
|
**Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere.
|