Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

feat: Deep-link Builder instances (#5923)

Oleg Isonen9ce325b94cfb
diff --git a/apps/builder/app/builder/features/publish/publish.tsx b/apps/builder/app/builder/features/publish/publish.tsx
index 59f4bb080b..35712e952d 100644
--- a/apps/builder/app/builder/features/publish/publish.tsx
+++ b/apps/builder/app/builder/features/publish/publish.tsx
@@ -47,7 +47,9 @@ import {
} from "~/shared/nano-states";
import { $selectedPageId } from "~/shared/nano-states";
import {
+ $authToken,
$authTokenPermissions,
+ $builderMode,
$editingPageId,
$permissions,
$stagingUsername,
@@ -89,15 +91,79 @@ import { RelativeTime } from "~/builder/shared/relative-time";
import cmsUpgradeBanner from "~/shared/cms-upgrade-banner.svg?url";
import { $currentSystem } from "~/shared/system";
import { getPublishUrl } from "./publish-url";
+import { builderUrl } from "~/shared/router-utils";
import {
getRestrictedFeatures,
type RestrictedFeature,
} from "./restricted-features";
import {
+ findPageAndSelectorByInstanceId,
formatPrePublishAuditFinding,
runPrePublishAudit,
+ type PrePublishAuditFinding,
} from "@webstudio-is/project-build/runtime";
+const PrePublishAuditError = ({
+ finding,
+}: {
+ finding: PrePublishAuditFinding;
+}) => {
+ const message = formatPrePublishAuditFinding(finding);
+ const { instanceId } = finding.location;
+ const pages = $pages.get();
+ const instances = $instances.get();
+ const project = $project.get();
+
+ if (
+ instanceId === undefined ||
+ pages === undefined ||
+ project === undefined ||
+ instances.has(instanceId) === false
+ ) {
+ return message;
+ }
+
+ const { pageId, instanceSelector } = findPageAndSelectorByInstanceId(
+ pages,
+ instances,
+ instanceId
+ );
+ const href = builderUrl({
+ projectId: project.id,
+ pageId: pageId === pages.homePageId ? undefined : pageId,
+ instanceId,
+ origin: window.location.origin,
+ authToken: $authToken.get(),
+ mode: $builderMode.get(),
+ });
+
+ return (
+ <>
+ {message}{" "}
+ <Link
+ href={href}
+ onClick={(event) => {
+ if (
+ event.button !== 0 ||
+ event.metaKey ||
+ event.ctrlKey ||
+ event.shiftKey ||
+ event.altKey
+ ) {
+ return;
+ }
+ event.preventDefault();
+ $selectedPageId.set(pageId);
+ selectInstance(instanceSelector);
+ $publishDialog.set("none");
+ }}
+ >
+ Show element
+ </Link>
+ </>
+ );
+};
+
const getPrePublishAuditError = () => {
const findings = runPrePublishAudit({
pages: $pages.get(),
@@ -108,7 +174,7 @@ const getPrePublishAuditError = () => {
metas: $registeredComponentMetas.get(),
});
const finding = findings.find(({ severity }) => severity === "error");
- return finding && formatPrePublishAuditFinding(finding);
+ return finding && <PrePublishAuditError finding={finding} />;
};
type ChangeProjectDomainProps = {
@@ -645,7 +711,7 @@ const PublishStatic = ({
}) => {
const project = useStore($project);
const [_, startTransition] = useTransition();
- const [publishError, setPublishError] = useState<string>();
+ const [publishError, setPublishError] = useState<JSX.Element | string>();
if (project == null) {
throw new Error("Project not found");
diff --git a/apps/builder/app/routes/_ui.(builder).tsx b/apps/builder/app/routes/_ui.(builder).tsx
index 2ceb885852..ba87a9be12 100644
--- a/apps/builder/app/routes/_ui.(builder).tsx
+++ b/apps/builder/app/routes/_ui.(builder).tsx
@@ -334,6 +334,9 @@ export const shouldRevalidate: ShouldRevalidateFunction = ({
currentUrlCopy.searchParams.delete("pageId");
nextUrlCopy.searchParams.delete("pageId");
+ currentUrlCopy.searchParams.delete("instanceId");
+ nextUrlCopy.searchParams.delete("instanceId");
+
currentUrlCopy.searchParams.delete("mode");
nextUrlCopy.searchParams.delete("mode");
diff --git a/apps/builder/app/shared/pages/use-switch-page.test.tsx b/apps/builder/app/shared/pages/use-switch-page.test.tsx
new file mode 100644
index 0000000000..251dacc1e1
--- /dev/null
+++ b/apps/builder/app/shared/pages/use-switch-page.test.tsx
@@ -0,0 +1,48 @@
+import { expect, test } from "vitest";
+import { createDefaultPages } from "@webstudio-is/project-build";
+import { $, renderData } from "@webstudio-is/template";
+import { __testing__ } from "./use-switch-page";
+
+const { getDeepLinkedInstanceSelection } = __testing__;
+
+test("resolves a deep-linked instance to its page and full selector", () => {
+ const pages = createDefaultPages({
+ homePageId: "home-page",
+ rootInstanceId: "body",
+ });
+ const { instances } = renderData(
+ <$.Body ws:id="body">
+ <$.Box ws:id="box">
+ <$.Heading ws:id="heading">Heading</$.Heading>
+ </$.Box>
+ </$.Body>
+ );
+ expect(
+ getDeepLinkedInstanceSelection({
+ instanceId: "heading",
+ canOpenPageTemplates: true,
+ pages,
+ instances,
+ })
+ ).toEqual({
+ pageId: "home-page",
+ instanceSelector: ["heading", "box", "body"],
+ });
+});
+
+test("ignores missing deep-linked instances", () => {
+ const pages = createDefaultPages({
+ homePageId: "home-page",
+ rootInstanceId: "body",
+ });
+ const { instances } = renderData(<$.Body ws:id="body"></$.Body>);
+
+ expect(
+ getDeepLinkedInstanceSelection({
+ instanceId: "missing",
+ canOpenPageTemplates: true,
+ pages,
+ instances,
+ })
+ ).toBeUndefined();
+});
diff --git a/apps/builder/app/shared/pages/use-switch-page.ts b/apps/builder/app/shared/pages/use-switch-page.ts
index 245f85dc21..ab16f89bee 100644
--- a/apps/builder/app/shared/pages/use-switch-page.ts
+++ b/apps/builder/app/shared/pages/use-switch-page.ts
@@ -1,19 +1,59 @@
import { useEffect } from "react";
import { useStore } from "@nanostores/react";
import { useNavigate } from "@remix-run/react";
-import { $pages, $project } from "~/shared/sync/data-stores";
+import { $instances, $pages, $project } from "~/shared/sync/data-stores";
import {
$authToken,
$canOpenPageTemplates,
+ $selectedInstanceSelector,
+ $selectedPageId,
$selectedPageHash,
$builderMode,
isBuilderMode,
+ selectInstance,
setBuilderMode,
} from "~/shared/nano-states";
import { builderPath } from "~/shared/router-utils";
import { $selectedPage } from "../nano-states";
import { selectPage } from "../nano-states";
-import { findPageByIdOrPath, isPageTemplate } from "@webstudio-is/sdk";
+import {
+ findPageByIdOrPath,
+ isPageTemplate,
+ type Instances,
+ type Pages,
+} from "@webstudio-is/sdk";
+import { findPageAndSelectorByInstanceId } from "@webstudio-is/project-build/runtime";
+
+const getDeepLinkedInstanceSelection = ({
+ instanceId,
+ canOpenPageTemplates,
+ pages,
+ instances,
+}: {
+ instanceId: string | null;
+ canOpenPageTemplates: boolean;
+ pages: Pages;
+ instances: Instances;
+}) => {
+ if (instanceId === null || instances.has(instanceId) === false) {
+ return;
+ }
+
+ const selection = findPageAndSelectorByInstanceId(
+ pages,
+ instances,
+ instanceId
+ );
+ const page = canOpenPageTemplates
+ ? findPageByIdOrPath(selection.pageId, pages, { includeTemplates: true })
+ : findPageByIdOrPath(selection.pageId, pages);
+ if (page?.rootInstanceId !== selection.instanceSelector.at(-1)) {
+ return;
+ }
+ return selection;
+};
+
+export const __testing__ = { getDeepLinkedInstanceSelection };
const setPageStateFromUrl = () => {
const searchParams = new URLSearchParams(window.location.search);
@@ -41,6 +81,17 @@ const setPageStateFromUrl = () => {
)?.id ?? pages.homePageId;
$selectedPageHash.set({ hash: searchParams.get("pageHash") ?? "" });
+ const instanceSelection = getDeepLinkedInstanceSelection({
+ instanceId: searchParams.get("instanceId"),
+ canOpenPageTemplates: $canOpenPageTemplates.get(),
+ pages,
+ instances: $instances.get(),
+ });
+ if (instanceSelection !== undefined) {
+ $selectedPageId.set(instanceSelection.pageId);
+ selectInstance(instanceSelection.instanceSelector);
+ return;
+ }
selectPage(pageId);
};
@@ -58,6 +109,7 @@ export const useSyncPageUrl = () => {
const page = useStore($selectedPage);
const pageHash = useStore($selectedPageHash);
const builderMode = useStore($builderMode);
+ const selectedInstanceSelector = useStore($selectedInstanceSelector);
const canOpenPageTemplate = useStore($canOpenPageTemplates);
// Get pageId and pageHash from URL
@@ -91,31 +143,42 @@ export const useSyncPageUrl = () => {
const searchParamsPageId = searchParams.get("pageId") ?? pages.homePageId;
const searchParamsPageHash = searchParams.get("pageHash") ?? "";
- const searParamsModeRaw = searchParams.get("mode");
- const searParamsMode = isBuilderMode(searParamsModeRaw)
- ? searParamsModeRaw
+ const searchParamsInstanceId = searchParams.get("instanceId") ?? undefined;
+ const searchParamsModeRaw = searchParams.get("mode");
+ const searchParamsMode = isBuilderMode(searchParamsModeRaw)
+ ? searchParamsModeRaw
: undefined;
+ const builderModeParam = builderMode === "design" ? undefined : builderMode;
const searchParamsSafemode = searchParams.get("safemode");
-
- // Do not navigate on popstate change or if params match
- if (
+ const selectedInstanceId = selectedInstanceSelector?.[0];
+ const instanceId =
+ selectedInstanceId === page.rootInstanceId ||
+ $instances.get().has(selectedInstanceId ?? "") === false
+ ? undefined
+ : selectedInstanceId;
+
+ const isSamePageState =
searchParamsPageId === page.id &&
searchParamsPageHash === pageHash.hash &&
- searParamsMode === builderMode
- ) {
+ searchParamsMode === builderModeParam;
+
+ // Do not navigate on popstate change or if params match
+ if (isSamePageState && searchParamsInstanceId === instanceId) {
return;
}
navigate(
builderPath({
pageId: page.id === pages.homePageId ? undefined : page.id,
+ instanceId,
authToken: $authToken.get(),
pageHash: pageHash.hash === "" ? undefined : pageHash.hash,
- mode: builderMode === "design" ? undefined : builderMode,
+ mode: builderModeParam,
safemode: searchParamsSafemode === "true",
- })
+ }),
+ { replace: isSamePageState }
);
- }, [builderMode, navigate, page, pageHash]);
+ }, [builderMode, navigate, page, pageHash, selectedInstanceSelector]);
useEffect(() => {
const pages = $pages.get();
diff --git a/apps/builder/app/shared/router-utils/path-utils.test.ts b/apps/builder/app/shared/router-utils/path-utils.test.ts
new file mode 100644
index 0000000000..f69adc1716
--- /dev/null
+++ b/apps/builder/app/shared/router-utils/path-utils.test.ts
@@ -0,0 +1,25 @@
+import { expect, test } from "vitest";
+import { builderPath, builderUrl } from "./path-utils";
+
+test("includes an instance deep link in builder paths", () => {
+ expect(
+ builderPath({
+ pageId: "page-id",
+ instanceId: "instance-id",
+ mode: "content",
+ })
+ ).toBe("/?pageId=page-id&instanceId=instance-id&mode=content");
+});
+
+test("includes an instance deep link in builder urls", () => {
+ expect(
+ builderUrl({
+ projectId: "project-id",
+ pageId: "page-id",
+ instanceId: "instance-id",
+ origin: "https://wstd.dev",
+ })
+ ).toBe(
+ "https://p-project-id.wstd.dev/?pageId=page-id&instanceId=instance-id"
+ );
+});
diff --git a/apps/builder/app/shared/router-utils/path-utils.ts b/apps/builder/app/shared/router-utils/path-utils.ts
index 314ac2a60e..0da1acc33c 100644
--- a/apps/builder/app/shared/router-utils/path-utils.ts
+++ b/apps/builder/app/shared/router-utils/path-utils.ts
@@ -13,21 +13,26 @@ const searchParams = (params: Record<string, string | undefined | null>) => {
return asString === "" ? "" : `?${asString}`;
};
+export type BuilderLinkParams = {
+ pageId?: string;
+ instanceId?: string;
+ authToken?: string;
+ pageHash?: string;
+ mode?: BuilderMode;
+ safemode?: boolean;
+};
+
export const builderPath = ({
pageId,
+ instanceId,
authToken,
pageHash,
mode,
safemode = false,
-}: {
- pageId?: string;
- authToken?: string;
- pageHash?: string;
- mode?: "preview" | "content";
- safemode?: boolean;
-} = {}) => {
+}: BuilderLinkParams = {}) => {
return `/${searchParams({
pageId,
+ instanceId,
authToken,
pageHash,
mode,
@@ -35,39 +40,28 @@ export const builderPath = ({
})}`;
};
-export const builderUrl = (props: {
+export const builderUrl = ({
+ projectId,
+ origin,
+ ...link
+}: BuilderLinkParams & {
projectId: string;
- pageId?: string;
origin: string;
- authToken?: string;
- mode?: BuilderMode;
- safemode?: boolean;
}) => {
- const authServerOrigin = getAuthorizationServerOrigin(props.origin);
+ const authServerOrigin = getAuthorizationServerOrigin(origin);
- const url = new URL(
- builderPath({
- pageId: props.pageId,
- authToken: props.authToken,
- safemode: props.safemode,
- }),
- authServerOrigin
- );
+ const url = new URL(builderPath(link), authServerOrigin);
const fragments = url.host.split(".");
if (fragments.length <= 3) {
- fragments.splice(0, 0, "p-" + props.projectId);
+ fragments.splice(0, 0, "p-" + projectId);
} else {
// staging | development branches
- fragments[0] = "p-" + props.projectId + "-dot-" + fragments[0];
+ fragments[0] = "p-" + projectId + "-dot-" + fragments[0];
}
url.host = fragments.join(".");
- if (props.mode !== undefined) {
- url.searchParams.set("mode", props.mode);
- }
-
return url.href;
};