): void;
substituteComponent(component: React.ComponentType
, name: ComponentLookupSpec): void;
protected internalSubstituteComponent
(component: React.ComponentType
, name: ComponentLookupSpec, codeComponentHelpers: ComponentHelpers>> | undefined): void;
abstract registerComponent>(component: T, meta: CodeComponentMeta>): void;
abstract registerFunction any>(fn: F, meta: CustomFunctionMeta): void;
abstract registerGlobalContext>(context: T, meta: GlobalContextMeta>): void;
abstract registerTrait(trait: string, meta: TraitMeta): void;
abstract registerToken(token: TokenRegistration): void;
protected refreshRegistry(): void;
isRegistryEmpty(): boolean;
clearRegistry(): void;
setGlobalVariants(globalVariants: GlobalVariantSpec[]): void;
getGlobalVariants(): GlobalVariantSpec[];
registerPrefetchedBundle(bundle: LoaderBundleOutput): void;
getLookup(): ComponentLookup;
getActiveVariation(opts: Omit[0], "splits">): Promise>;
getTeamIds(): string[];
getProjectIds(): string[];
loadServerQueriesModule(fileName: string): any;
}
declare interface BuiltinRegisteredModules {
react: react;
"react-dom": reactDom;
"react/jsx-runtime": reactJsxRuntime;
"react/jsx-dev-runtime": reactJsxDevRuntime;
"@plasmicapp/query": plasmicappQuery;
"@plasmicapp/data-sources-context": plasmicappDataSourcesContext;
"@plasmicapp/host": plasmicappHost;
"@plasmicapp/loader-runtime-registry": {
components: Record>;
globalVariantHooks: Record any>;
codeComponentHelpers: Record>;
functions: Record any>;
};
}
export declare type CodeComponentMeta = Omit, "importPath" | "componentHelpers" | "states"> & {
/**
* The path to be used when importing the component in the generated code.
* It can be the name of the package that contains the component, or the path
* to the file in the project (relative to the root directory).
* Optional: not used by Plasmic headless API, only by codegen.
*/
importPath?: string;
/**
* The states helpers are registered together with the states for the Plasmic headless API
*/
states?: Record & StateHelpers>;
/**
* Helper function to enable data extraction when running Plasmic from
* Next.js App Router.
*/
getServerInfo?: (props: P, ops: ReactServerOps) => ServerInfo;
};
declare class ComponentLookup {
private bundle;
private registry;
constructor(bundle: LoaderBundleOutput_2, registry: Registry);
getComponentMeta(spec: ComponentLookupSpec): ComponentMeta | undefined;
getComponent
(spec: ComponentLookupSpec, opts?: {
forceOriginal?: boolean;
}): any;
hasComponent(spec: ComponentLookupSpec): boolean;
getGlobalContexts(): {
meta: GlobalGroupMeta;
context: any;
}[];
/** Returns StyleTokensProvider if the project has style token overrides. */
maybeGetStyleTokensProvider(spec: ComponentLookupSpec, styleTokenOverridesProjectId?: string): any;
getGlobalContextsProvider(spec: ComponentLookupSpec): any;
getRootProvider(): any;
getCss(): AssetModule[];
getRemoteFonts(): FontMeta[];
}
export declare type ComponentLookupSpec = string | {
name: string;
projectId?: string;
isCode?: boolean;
};
export { ComponentMeta }
export declare interface ComponentRenderData {
entryCompMetas: (ComponentMeta_2 & {
params?: Record;
})[];
bundle: LoaderBundleOutput;
remoteFontUrls: string[];
}
export declare const convertBundlesToComponentRenderData: (bundles: LoaderBundleOutput_2[], compMetas: ComponentMeta[]) => ComponentRenderData | null;
export declare type CustomFunctionMeta any> = Omit, "importPath"> & {
/**
* The path to be used when importing the function in the generated code.
* It can be the name of the package that contains the function, or the path
* to the file in the project (relative to the root directory).
* Optional: not used by Plasmic headless API, only by codegen.
*/
importPath?: string;
};
export { DataCtxReader }
export { DataProvider }
/**
* Performs a prepass over Plasmic content, kicking off the necessary
* data fetches, and populating the fetched data into a cache. This
* cache can be passed as prefetchedQueryData into PlasmicRootProvider.
*
* To limit rendering errors that can occur when you do this, we recommend
* that you pass in _only_ the PlasmicComponents that you are planning to use
* as the argument. For example:
*
* const cache = await extractPlasmicQueryData(
*
*
*
* ...
*
* );
*
* If your PlasmicComponent will be wrapping components that require special
* context set up, you should also wrap the element above with those context
* providers.
*
* You should avoid passing in elements that are not related to Plasmic, as any
* rendering errors from those elements during the prepass may result in data
* not being populated in the cache.
*
* @param element a React element containing instances of PlasmicComponent.
* Will attempt to satisfy all data needs from usePlasmicDataQuery()
* in this element tree.
* @returns an object mapping query key to fetched data
*/
export declare function extractPlasmicQueryData(element: React.ReactElement): Promise>;
/**
* Pre-renders a Plasmic tree to extract query data.
*
* This is intended to be used for server-rendered apps.
*/
export declare function extractPlasmicQueryDataFromElement(loader: PlasmicComponentLoader, lookup: ComponentLookupSpec, opts?: {
prefetchedData?: ComponentRenderData;
componentProps?: any;
globalVariants?: GlobalVariantSpec[];
prefetchedQueryData?: Record;
}): Promise>;
export declare interface FetchComponentDataOpts {
/**
* Will fetch either code targeting SSR or browser hydration in the
* returned bundle.
*
* By default, the target is browser. That's okay, because even when
* doing SSR, as long as you are using the same instance of PlasmicLoader
* that was used to fetch component data, it will still know how to get at
* the server code.
*
* But, if you are building your own SSR solution, where fetching and rendering
* are using different instances of PlasmicLoader, then you'll want to make
* sure that when you fetch, you are fetching the right one to be used in the
* right environment for either SSR or browser hydration.
*/
target?: "server" | "browser";
}
declare type FetchPagesOpts = {
/**
* Whether to include dynamic pages in fetchPages() output. A page is
* considered dynamic if its path contains some param between brackets,
* e.g. "[slug]".
*/
includeDynamicPages?: boolean;
};
export { GlobalActionsContext }
export { GlobalActionsProvider }
export declare type GlobalContextMeta = Omit, "importPath"> & {
/**
* The path to be used when importing the component in the generated code.
* It can be the name of the package that contains the component, or the path
* to the file in the project (relative to the root directory).
* Optional: not used by Plasmic headless API, only by codegen.
*/
importPath?: string;
};
export declare interface GlobalVariantSpec {
name: string;
projectId?: string;
value: any;
}
/**
* Hydrates a Plasmic tree in the target element.
*
* Uses React DOM client API `hydrateRoot`, which is intended to be used from
* server-rendered apps.
*/
export declare function hydrateFromElement(loader: PlasmicComponentLoader, target: HTMLElement, lookup: ComponentLookupSpec, opts?: {
prefetchedData?: ComponentRenderData;
componentProps?: any;
globalVariants?: GlobalVariantSpec[];
prefetchedQueryData?: Record;
}): ReactDOMClient.Root;
export declare interface InitOptions {
projects: {
id: string;
token: string;
version?: string;
}[];
cache?: LoaderBundleCache;
platform?: "react" | "nextjs" | "gatsby";
platformOptions?: {
nextjs?: {
appDir: boolean;
};
};
preview?: boolean;
/** Fallback for apiHost and cdnHost. */
host?: string;
/** Used for fetching/previewing unpublished content. */
apiHost?: string;
/** Used for fetching published content. */
cdnHost?: string;
onClientSideFetch?: "warn" | "error";
i18n?: {
keyScheme: "content" | "hash" | "path";
tagPrefix?: string;
};
/**
* By default, fetchComponentData() and fetchPages() calls cached in memory
* with the PlasmicComponentLoader instance. If alwaysFresh is true, then
* data is always freshly fetched over the network.
*/
alwaysFresh?: boolean;
/**
* If true, generated code from the server won't include page metadata tags
*/
skipHead?: boolean;
/**
* @deprecated No-op. Native fetch is always used now.
*/
nativeFetch?: boolean;
/**
* If true, will not redirect to the codegen server automatically, and will
* try to reuse the existing bundle in the cache.
*/
manualRedirect?: boolean;
}
export declare function initPlasmicLoader(opts: InitOptions): PlasmicComponentLoader;
export declare class InternalPlasmicComponentLoader extends BaseInternalPlasmicComponentLoader {
private readonly roots;
constructor(opts: InitOptions);
registerComponent>(component: T, meta: CodeComponentMeta>): void;
registerFunction any>(fn: F, meta: CustomFunctionMeta): void;
registerGlobalContext>(context: T, meta: GlobalContextMeta>): void;
registerTrait(trait: string, meta: TraitMeta): void;
registerToken(token: TokenRegistration): void;
subscribePlasmicRoot(watcher: PlasmicRootWatcher): void;
unsubscribePlasmicRoot(watcher: PlasmicRootWatcher): void;
refreshRegistry(): void;
}
/**
* Check if `lookup` resolves to `pagePath`. If it's a match, return an object
* containing path params; otherwise, return false.
*
* For example,
* - `matchesPagePath("/hello/[name]", "/hello/world")` -> `{params: {name:
* "world"}}`
* - `matchesPagePath("/hello/[name]", "/")` -> `false`
* - `matchesPagePath("/hello/[...catchall]", "/hello/a/b/c")` -> `{params: {catchall: ["a", "b", "c"]}}`
* - `matchesPagePath("/hello/[[...catchall]]", "/hello/")` -> `{params: {catchall: []}}`
* - `matchesPagePath("/", "")` -> `{params: {}}`
*/
export declare function matchesPagePath(pattern: string, path: string): false | {
params: Record;
};
export { PageMeta }
export { PageMetadata }
export { PageParamsProvider }
declare type ParamsRecord = Record;
export { PlasmicCanvasContext }
export { PlasmicCanvasHost }
export declare function PlasmicComponent(props: {
/**
* Name of the component to render, or the path of the page component
*/
component: string;
/**
* Optionally specify a projectId if there are multiple components
* of the same name from different projects
*/
projectId?: string;
/**
* If you used registerComponent(), then if the name matches a registered
* component, that component is used. If you want the Plasmic-generated
* component instead, specify forceOriginal.
*/
forceOriginal?: boolean;
componentProps?: any;
}): React_2.ReactElement | null;
/**
* Library for fetching component data, and registering
* custom components.
*/
export declare class PlasmicComponentLoader {
private __internal;
constructor(internal: BaseInternalPlasmicComponentLoader);
/**
* Sets global variants to be used for all components. Note that
* this is not reactive, and will not re-render all components
* already mounted; instead, it should be used to activate global
* variants that should always be activated for the lifetime of this
* app. If you'd like to reactively change the global variants,
* you should specify them via
*/
setGlobalVariants(globalVariants: GlobalVariantSpec[]): void;
registerModules(modules: Record): void;
/**
* Register custom components that should be swapped in for
* components defined in your project. You can use this to
* swap in / substitute a Plasmic component with a "real" component.
*/
substituteComponent(component: React.ComponentType
, name: ComponentLookupSpec): void;
/**
* Register code components to be used on Plasmic Editor.
*/
registerComponent>(component: T, meta: CodeComponentMeta>): void;
registerFunction any>(fn: F, meta: CustomFunctionMeta): void;
registerGlobalContext>(context: T, meta: GlobalContextMeta>): void;
registerTrait(trait: string, meta: TraitMeta): void;
registerToken(token: TokenRegistration): void;
/**
* Pre-fetches component data needed to for PlasmicLoader to render
* these components. Should be passed into PlasmicRootProvider as
* the prefetchedData prop.
*
* You can look up a component either by:
* - the name of the component
* - the path for a page component
* - an array of strings that make up parts of the path
* - object { name: "name_or_path", projectId: ...}, to specify which project
* to use, if multiple projects have the same component name
*
* Throws an Error if a specified component to fetch does not exist in
* the Plasmic project.
*/
fetchComponentData(...specs: ComponentLookupSpec[]): Promise;
fetchComponentData(specs: ComponentLookupSpec[], opts?: FetchComponentDataOpts): Promise;
/**
* Like fetchComponentData(), but returns null instead of throwing an Error
* when a component is not found. Useful when you are implementing a catch-all
* page and want to check if a specific path had been defined for Plasmic.
*/
maybeFetchComponentData(...specs: ComponentLookupSpec[]): Promise;
maybeFetchComponentData(specs: ComponentLookupSpec[], opts?: FetchComponentDataOpts): Promise;
/**
* Returns all the page component metadata for these projects.
*/
fetchPages(opts?: FetchPagesOpts): Promise;
/**
* Returns all components metadata for these projects.
*/
fetchComponents(): Promise;
protected _getActiveVariation(opts: Parameters[0]): Promise>;
getActiveVariation(opts: {
known?: Record;
traits: Record;
}): Promise>;
getChunksUrl(bundle: LoaderBundleOutput, modules: CodeModule[]): string;
getExternalVariation(variation: Record, filters?: Parameters[2]): Record;
getActiveSplits(): Split[];
clearCache(): void;
getExecFuncModule(renderData: ComponentRenderData, fileNameKey: "serverQueriesExecFuncFileName"): any;
getPlasmicQueriesData(renderData: ComponentRenderData, ctx: Record, props?: Record): Promise;
/**
* @deprecated Use {@link PlasmicComponentLoader.getPlasmicQueriesData} instead.
*/
unstable__getServerQueriesData(renderData: ComponentRenderData, ctx: Record, props?: Record): Promise;
getPlasmicMetadata(renderData: ComponentRenderData, props: {
params: Promise | ParamsRecord;
query: Promise | ParamsRecord;
}): Promise;
/**
* @deprecated Use {@link PlasmicComponentLoader.getPlasmicMetadata} instead.
*/
unstable__generateMetadata(renderData: ComponentRenderData, props: {
params: Promise | ParamsRecord;
query: Promise | ParamsRecord;
}): Promise;
}
/**
* PlasmicRootProvider should be used at the root of your page
* or application.
*/
export declare function PlasmicRootProvider(props: {
/**
* The global PlasmicComponentLoader instance you created via
* initPlasmicLoader().
*/
loader: PlasmicComponentLoader;
/**
* Global variants to activate for Plasmic components
*/
globalVariants?: GlobalVariantSpec[];
children?: React_2.ReactNode;
/**
* If true, will skip rendering css
*/
skipCss?: boolean;
/**
* If true, will skip installing fonts
*/
skipFonts?: boolean;
/**
* If you have pre-fetched component data via PlasmicComponentLoader,
* you can pass them in here; PlasmicComponent will avoid fetching
* component data that have already been pre-fetched.
*/
prefetchedData?: ComponentRenderData;
/**
* If you have pre-fetched data that are needed by usePlasmicQueryData(),
* then pass in the pre-fetched cache here, mapping query key to fetched data.
*/
prefetchedQueryData?: Record;
/**
* Specifies whether usePlasmicQueryData() should be operating in suspense mode
* (throwing promises).
*/
suspenseForQueryData?: boolean;
/**
* Override your Global Contexts Provider props. This is a map from
* globalContextComponentNameProps to object of props to use for that
* component.
*/
globalContextsProps?: Record;
/**
* Specifies a mapping of split id to slice id that should be activated
*/
variation?: Record;
/**
* Translator function to be used for text blocks
*/
translator?: PlasmicTranslator;
/**
* Head component to use in PlasmicHead component (e.g. Head from next/head
* or Helmet from react-helmet).
*/
Head?: React_2.ComponentType;
/**
* Link component to use. Can be any component that takes in props passed
* to an tag.
*/
Link?: React_2.ComponentType;
/**
* Page route without params substitution (e.g. /products/[slug]).
*/
pageRoute?: string;
/**
* Page path parameters (e.g. {slug: "foo"} if page path is
* /products/[slug] and URI is /products/foo).
*/
pageParams?: Record;
/**
* Page query parameters (e.g. {q: "foo"} if page path is
* /some/path?q=foo).
*/
pageQuery?: Record;
/**
* Defaults to false. If true, query params derived from `location.search` sync
* with client-side history changes. `pageQuery` prop is used as a fallback during SSR.
*/
trackQueryParams?: boolean;
/**
* Whether the internal Plasmic React.Suspense boundaries should be removed
*/
disableLoadingBoundary?: boolean;
/**
* Whether the root React.Suspense boundary should be removed
*/
disableRootLoadingBoundary?: boolean;
/**
* Fallback value for React.Suspense boundary
*/
suspenseFallback?: React_2.ReactNode;
/**
* When Plasmic loads components from multiple projects, we must choose a style token overrides to use that will apply to all components under the root PlasmicComponent.
*
* If styleTokenOverridesProjectId is set, all PlasmicComponents and their subtrees will use the specified project's style token overrides.
* If styleTokenOverridesProjectId it not set, each PlasmicComponent and its subtree will use the style token overrides of the root PlasmicComponent's project.
*/
styleTokenOverridesProjectId?: string;
} & PlasmicDataSourceContextValue): React_2.JSX.Element;
declare interface PlasmicRootWatcher {
onDataFetched?: () => void;
}
export declare type PlasmicTranslator = (str: string, opts?: {
components?: {
[key: string]: React_2.ReactElement | React_2.ReactFragment;
};
}) => React_2.ReactNode;
export { PlasmicTranslatorContext }
export { PropType }
/**
* Helper functions to describe code component behaviors, in order to allow
* data extraction in RSC / Next.js App routing.
*/
declare interface ReactServerOps {
readDataEnv: typeof useDataEnv;
readDataSelector: typeof useSelector;
readDataSelectors: typeof useSelectors;
/**
* The contexts are passed using a key instead of the context provider
* Notice it cannot access the default context value if none has been provided,
* since React server components cannot create contexts.
*/
readContext: (contextKey: string) => any;
/**
* Allows data fetching from the code component and caching the result,
* which will be stored in the `queryCache` returned by
* `extractPlasmicQueryData`.
*/
fetchData: typeof useMutablePlasmicQueryData;
}
/**
* Renders a Plasmic tree in the target element.
*
* Uses React DOM client API `createRoot`, which is intended to be used from
* client-rendered apps.
*/
export declare function renderToElement(loader: PlasmicComponentLoader, target: HTMLElement, lookup: ComponentLookupSpec, opts?: {
prefetchedData?: ComponentRenderData;
componentProps?: any;
globalVariants?: GlobalVariantSpec[];
prefetchedQueryData?: Record;
pageParams?: Record;
pageQuery?: Record;
}): ReactDOMClient.Root;
/**
* Renders a Plasmic tree to a string.
*
* Uses React DOM server API `renderToString`, which is intended to be used for
* server-rendered apps.
*/
export declare function renderToString(loader: PlasmicComponentLoader, lookup: ComponentLookupSpec, opts?: {
prefetchedData?: ComponentRenderData;
componentProps?: any;
globalVariants?: GlobalVariantSpec[];
prefetchedQueryData?: Record;
}): string;
export { repeatedElement }
/**
* Each child of a code component might receive separate `DataProvider` and
* Context values.
*/
declare interface ServerChildData {
providedData?: ServerProvidedData | ServerProvidedData[];
providedContexts?: ServerProvidedContext | ServerProvidedContext[];
node: React.ReactNode;
}
declare interface ServerInfo {
/**
* Optional: Indicates the React Nodes created by the component and the
* respective contexts provided to them. If not specified, it will render the
* children passed to the component as props.
*/
children?: ServerChildData | ServerChildData[];
providedData?: ServerProvidedData | ServerProvidedData[];
providedContexts?: ServerProvidedContext | ServerProvidedContext[];
}
/**
* Provides a new value for a given context key, similar to Context.Provider.
* The context itself is not available (RSC doesn't allow calling
* `createContext`) so each context will need to be represented as a unique
* "context key". Also it means the default context value is not available
* in case no value is passed (and reading that context will return `undefined`)
*/
declare interface ServerProvidedContext {
/**
* Identifier to the context, required to read it later via
* `ReactServerOps.readContext()`.
*/
contextKey: string;
/**
* Context value being provided (similar to `Context.Provider`).
*/
value: any;
}
/**
* Represents data provided by a code component via `DataProvider`
*/
declare interface ServerProvidedData {
name: string;
data: any;
}
export { TokenRegistration }
export { useDataEnv }
export { usePlasmicCanvasComponentInfo }
export { usePlasmicCanvasContext }
/**
* Hook that fetches and returns a React component for rendering the argument
* Plasmic component. Returns undefined if the component data is still
* being fetched.
*
* @param opts.forceOriginal if you used PlasmicComponentLoader.registerComponent,
* then normally usePlasmicComponent will return the registered component.
* You can set forceOriginal to true if you want to return the Plasmic-generated
* component instead.
*/
export declare function usePlasmicComponent(spec: ComponentLookupSpec, opts?: {
forceOriginal?: boolean;
}): P;
export { usePlasmicQueryData }
export { useSelector }
export { useSelectors }
export { }