@puckeditor/cli 0.24.0-canary.10b39dc7
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/LICENSE +21 -0
- package/README.md +54 -0
- package/dist/bin.mjs +10343 -0
- package/dist/docs/api-reference/actions.md +63 -0
- package/dist/docs/api-reference/components/action-bar-action.md +35 -0
- package/dist/docs/api-reference/components/action-bar-group.md +24 -0
- package/dist/docs/api-reference/components/action-bar-label.md +25 -0
- package/dist/docs/api-reference/components/action-bar-separator.md +16 -0
- package/dist/docs/api-reference/components/action-bar.md +32 -0
- package/dist/docs/api-reference/components/auto-field.md +63 -0
- package/dist/docs/api-reference/components/drawer-item.md +75 -0
- package/dist/docs/api-reference/components/drawer.md +29 -0
- package/dist/docs/api-reference/components/drop-zone.md +232 -0
- package/dist/docs/api-reference/components/field-label.md +138 -0
- package/dist/docs/api-reference/components/inline-text-field.md +77 -0
- package/dist/docs/api-reference/components/puck-components.md +19 -0
- package/dist/docs/api-reference/components/puck-fields.md +39 -0
- package/dist/docs/api-reference/components/puck-layout.md +27 -0
- package/dist/docs/api-reference/components/puck-outline.md +19 -0
- package/dist/docs/api-reference/components/puck-preview.md +39 -0
- package/dist/docs/api-reference/components/puck.md +561 -0
- package/dist/docs/api-reference/components/render.md +94 -0
- package/dist/docs/api-reference/components/rich-text-menu-control.md +87 -0
- package/dist/docs/api-reference/components/rich-text-menu-group.md +27 -0
- package/dist/docs/api-reference/components/rich-text-menu.md +99 -0
- package/dist/docs/api-reference/components.md +32 -0
- package/dist/docs/api-reference/configuration/component-config.md +569 -0
- package/dist/docs/api-reference/configuration/config.md +108 -0
- package/dist/docs/api-reference/configuration.md +4 -0
- package/dist/docs/api-reference/data-model/app-state.md +168 -0
- package/dist/docs/api-reference/data-model/component-data.md +62 -0
- package/dist/docs/api-reference/data-model/data.md +95 -0
- package/dist/docs/api-reference/data-model/item-selector.md +34 -0
- package/dist/docs/api-reference/data-model/root-data.md +59 -0
- package/dist/docs/api-reference/data-model.md +8 -0
- package/dist/docs/api-reference/dictionary.md +172 -0
- package/dist/docs/api-reference/field-transforms.md +51 -0
- package/dist/docs/api-reference/fields/array.md +211 -0
- package/dist/docs/api-reference/fields/base.md +96 -0
- package/dist/docs/api-reference/fields/custom.md +193 -0
- package/dist/docs/api-reference/fields/external.md +413 -0
- package/dist/docs/api-reference/fields/number.md +132 -0
- package/dist/docs/api-reference/fields/object.md +78 -0
- package/dist/docs/api-reference/fields/radio.md +82 -0
- package/dist/docs/api-reference/fields/richtext.md +422 -0
- package/dist/docs/api-reference/fields/select.md +79 -0
- package/dist/docs/api-reference/fields/slot.md +302 -0
- package/dist/docs/api-reference/fields/text.md +93 -0
- package/dist/docs/api-reference/fields/textarea.md +93 -0
- package/dist/docs/api-reference/fields.md +16 -0
- package/dist/docs/api-reference/functions/migrate.md +204 -0
- package/dist/docs/api-reference/functions/register-overlay-portal.md +45 -0
- package/dist/docs/api-reference/functions/resolve-all-data.md +27 -0
- package/dist/docs/api-reference/functions/set-deep.md +55 -0
- package/dist/docs/api-reference/functions/transform-props.md +51 -0
- package/dist/docs/api-reference/functions/use-get-puck.md +24 -0
- package/dist/docs/api-reference/functions/use-puck.md +43 -0
- package/dist/docs/api-reference/functions/walk-tree.md +88 -0
- package/dist/docs/api-reference/functions.md +8 -0
- package/dist/docs/api-reference/overrides/action-bar.md +35 -0
- package/dist/docs/api-reference/overrides/component-overlay.md +41 -0
- package/dist/docs/api-reference/overrides/drawer-item.md +24 -0
- package/dist/docs/api-reference/overrides/drawer.md +19 -0
- package/dist/docs/api-reference/overrides/field-label.md +18 -0
- package/dist/docs/api-reference/overrides/field-types.md +51 -0
- package/dist/docs/api-reference/overrides/fields.md +19 -0
- package/dist/docs/api-reference/overrides/header-actions.md +24 -0
- package/dist/docs/api-reference/overrides/header.md +29 -0
- package/dist/docs/api-reference/overrides/iframe.md +32 -0
- package/dist/docs/api-reference/overrides/outline.md +19 -0
- package/dist/docs/api-reference/overrides/preview.md +19 -0
- package/dist/docs/api-reference/overrides/puck.md +19 -0
- package/dist/docs/api-reference/overrides.md +28 -0
- package/dist/docs/api-reference/permissions.md +55 -0
- package/dist/docs/api-reference/plugin.md +112 -0
- package/dist/docs/api-reference/plugins/blocks-plugin.md +57 -0
- package/dist/docs/api-reference/plugins/fields-plugin.md +68 -0
- package/dist/docs/api-reference/plugins/legacy-side-bar-plugin.md +54 -0
- package/dist/docs/api-reference/plugins/outline-plugin.md +57 -0
- package/dist/docs/api-reference/puck-api.md +278 -0
- package/dist/docs/api-reference/theming/action-bar.md +32 -0
- package/dist/docs/api-reference/theming/button.md +65 -0
- package/dist/docs/api-reference/theming/canvas.md +20 -0
- package/dist/docs/api-reference/theming/computed-values.md +194 -0
- package/dist/docs/api-reference/theming/drawer.md +34 -0
- package/dist/docs/api-reference/theming/fields.md +70 -0
- package/dist/docs/api-reference/theming/global.md +127 -0
- package/dist/docs/api-reference/theming/header.md +19 -0
- package/dist/docs/api-reference/theming/icon-button.md +28 -0
- package/dist/docs/api-reference/theming/outline.md +35 -0
- package/dist/docs/api-reference/theming/plugin-bar.md +24 -0
- package/dist/docs/api-reference/theming/sidebar.md +19 -0
- package/dist/docs/api-reference/theming/slot.md +27 -0
- package/dist/docs/cli.md +284 -0
- package/dist/docs/extending-puck/composition.md +54 -0
- package/dist/docs/extending-puck/custom-fields.md +133 -0
- package/dist/docs/extending-puck/field-transforms.md +89 -0
- package/dist/docs/extending-puck/internal-puck-api.md +96 -0
- package/dist/docs/extending-puck/plugins.md +159 -0
- package/dist/docs/extending-puck/theming.md +88 -0
- package/dist/docs/extending-puck/ui-overrides.md +134 -0
- package/dist/docs/getting-started.md +68 -0
- package/dist/docs/guides/migrations/dropzones-to-slots.md +138 -0
- package/dist/docs/index.json +466 -0
- package/dist/docs/index.md +37 -0
- package/dist/docs/integrating-puck/categories.md +92 -0
- package/dist/docs/integrating-puck/component-configuration.md +159 -0
- package/dist/docs/integrating-puck/data-migration.md +86 -0
- package/dist/docs/integrating-puck/dynamic-fields.md +86 -0
- package/dist/docs/integrating-puck/dynamic-props.md +137 -0
- package/dist/docs/integrating-puck/external-data-sources.md +149 -0
- package/dist/docs/integrating-puck/feature-toggling.md +121 -0
- package/dist/docs/integrating-puck/localization.md +228 -0
- package/dist/docs/integrating-puck/multi-column-layouts.md +226 -0
- package/dist/docs/integrating-puck/overlay-portals.md +25 -0
- package/dist/docs/integrating-puck/rich-text-editing.md +230 -0
- package/dist/docs/integrating-puck/root-configuration.md +171 -0
- package/dist/docs/integrating-puck/server-components.md +199 -0
- package/dist/docs/integrating-puck/styling.md +117 -0
- package/dist/docs/integrating-puck/viewports.md +75 -0
- package/dist/templates/astro/README.md +52 -0
- package/dist/templates/astro/_gitignore +24 -0
- package/dist/templates/astro/astro.config.mjs +14 -0
- package/dist/templates/astro/database.json +1 -0
- package/dist/templates/astro/package.json +25 -0
- package/dist/templates/astro/public/favicon.svg +9 -0
- package/dist/templates/astro/src/lib/pages.ts +21 -0
- package/dist/templates/astro/src/lib/resolve-puck-path.ts +19 -0
- package/dist/templates/astro/src/pages/[...puckPath].astro +25 -0
- package/dist/templates/astro/src/pages/api/pages.ts +18 -0
- package/dist/templates/astro/src/puck/editor.tsx +32 -0
- package/dist/templates/astro/src/puck/pages.ts +15 -0
- package/dist/templates/astro/src/puck/render.tsx +9 -0
- package/dist/templates/astro/src/puck.config.tsx +23 -0
- package/dist/templates/astro/tsconfig.json +14 -0
- package/dist/templates/astro-ai/README.md +64 -0
- package/dist/templates/astro-ai/_gitignore +24 -0
- package/dist/templates/astro-ai/astro.config.mjs +21 -0
- package/dist/templates/astro-ai/database.json +1 -0
- package/dist/templates/astro-ai/package.json +27 -0
- package/dist/templates/astro-ai/public/favicon.svg +9 -0
- package/dist/templates/astro-ai/src/lib/pages.ts +21 -0
- package/dist/templates/astro-ai/src/lib/resolve-puck-path.ts +19 -0
- package/dist/templates/astro-ai/src/pages/[...puckPath].astro +25 -0
- package/dist/templates/astro-ai/src/pages/api/pages.ts +18 -0
- package/dist/templates/astro-ai/src/pages/api/puck/[...all].ts +36 -0
- package/dist/templates/astro-ai/src/puck/editor.tsx +53 -0
- package/dist/templates/astro-ai/src/puck/pages.ts +15 -0
- package/dist/templates/astro-ai/src/puck/render.tsx +10 -0
- package/dist/templates/astro-ai/src/puck.config.tsx +23 -0
- package/dist/templates/astro-ai/tsconfig.json +14 -0
- package/dist/templates/express/README.md +66 -0
- package/dist/templates/express/_gitignore +16 -0
- package/dist/templates/express/database.json +1 -0
- package/dist/templates/express/package.json +20 -0
- package/dist/templates/express/src/index.ts +15 -0
- package/dist/templates/express/src/puck/pages.ts +44 -0
- package/dist/templates/express/tsconfig.json +12 -0
- package/dist/templates/express-ai/README.md +81 -0
- package/dist/templates/express-ai/_gitignore +16 -0
- package/dist/templates/express-ai/database.json +1 -0
- package/dist/templates/express-ai/package.json +22 -0
- package/dist/templates/express-ai/src/index.ts +17 -0
- package/dist/templates/express-ai/src/puck/cloud.ts +71 -0
- package/dist/templates/express-ai/src/puck/pages.ts +44 -0
- package/dist/templates/express-ai/tsconfig.json +12 -0
- package/dist/templates/hono/README.md +66 -0
- package/dist/templates/hono/_gitignore +32 -0
- package/dist/templates/hono/database.json +1 -0
- package/dist/templates/hono/package.json +20 -0
- package/dist/templates/hono/src/index.ts +21 -0
- package/dist/templates/hono/src/puck/pages.ts +32 -0
- package/dist/templates/hono/tsconfig.json +13 -0
- package/dist/templates/hono-ai/README.md +81 -0
- package/dist/templates/hono-ai/_gitignore +32 -0
- package/dist/templates/hono-ai/database.json +1 -0
- package/dist/templates/hono-ai/package.json +22 -0
- package/dist/templates/hono-ai/src/index.ts +23 -0
- package/dist/templates/hono-ai/src/puck/cloud.ts +30 -0
- package/dist/templates/hono-ai/src/puck/pages.ts +32 -0
- package/dist/templates/hono-ai/tsconfig.json +13 -0
- package/dist/templates/manifest.json +7 -0
- package/dist/templates/next/README.md +112 -0
- package/dist/templates/next/_gitignore +35 -0
- package/dist/templates/next/app/[...puckPath]/client.tsx +9 -0
- package/dist/templates/next/app/[...puckPath]/page.tsx +49 -0
- package/dist/templates/next/app/favicon.ico +0 -0
- package/dist/templates/next/app/layout.tsx +13 -0
- package/dist/templates/next/app/page.tsx +1 -0
- package/dist/templates/next/app/puck/[...puckPath]/client.tsx +20 -0
- package/dist/templates/next/app/puck/[...puckPath]/page.tsx +55 -0
- package/dist/templates/next/app/puck/api/route.ts +25 -0
- package/dist/templates/next/app/puck/page.tsx +3 -0
- package/dist/templates/next/app/styles.css +3 -0
- package/dist/templates/next/database.json +1 -0
- package/dist/templates/next/lib/get-page.ts +11 -0
- package/dist/templates/next/next.config.js +3 -0
- package/dist/templates/next/package.json +25 -0
- package/dist/templates/next/proxy.ts +27 -0
- package/dist/templates/next/puck.config.tsx +25 -0
- package/dist/templates/next/tsconfig/base.json +20 -0
- package/dist/templates/next/tsconfig/nextjs.json +21 -0
- package/dist/templates/next/tsconfig.json +8 -0
- package/dist/templates/next-ai/README.md +169 -0
- package/dist/templates/next-ai/_gitignore +35 -0
- package/dist/templates/next-ai/app/[...puckPath]/client.tsx +12 -0
- package/dist/templates/next-ai/app/[...puckPath]/page.tsx +49 -0
- package/dist/templates/next-ai/app/api/pages/route.ts +26 -0
- package/dist/templates/next-ai/app/api/puck/[...all]/route.ts +31 -0
- package/dist/templates/next-ai/app/layout.tsx +13 -0
- package/dist/templates/next-ai/app/page.tsx +1 -0
- package/dist/templates/next-ai/app/puck/[...puckPath]/client.tsx +38 -0
- package/dist/templates/next-ai/app/puck/[...puckPath]/page.tsx +57 -0
- package/dist/templates/next-ai/app/puck/page.tsx +3 -0
- package/dist/templates/next-ai/app/styles.css +3 -0
- package/dist/templates/next-ai/database.json +1 -0
- package/dist/templates/next-ai/lib/get-page.ts +11 -0
- package/dist/templates/next-ai/next.config.js +3 -0
- package/dist/templates/next-ai/package.json +27 -0
- package/dist/templates/next-ai/proxy.ts +27 -0
- package/dist/templates/next-ai/public/favicon.ico +0 -0
- package/dist/templates/next-ai/puck.config.tsx +25 -0
- package/dist/templates/next-ai/tsconfig/base.json +20 -0
- package/dist/templates/next-ai/tsconfig/nextjs.json +21 -0
- package/dist/templates/next-ai/tsconfig.json +8 -0
- package/dist/templates/react-router/README.md +113 -0
- package/dist/templates/react-router/_gitignore +6 -0
- package/dist/templates/react-router/app/components/puck-render.tsx +8 -0
- package/dist/templates/react-router/app/lib/pages.server.ts +29 -0
- package/dist/templates/react-router/app/lib/resolve-puck-path.server.ts +19 -0
- package/dist/templates/react-router/app/root.tsx +65 -0
- package/dist/templates/react-router/app/routes/_index.tsx +31 -0
- package/dist/templates/react-router/app/routes/puck-splat.tsx +95 -0
- package/dist/templates/react-router/app/routes.ts +7 -0
- package/dist/templates/react-router/database.json +1 -0
- package/dist/templates/react-router/package.json +33 -0
- package/dist/templates/react-router/public/favicon.ico +0 -0
- package/dist/templates/react-router/puck.config.tsx +23 -0
- package/dist/templates/react-router/react-router.config.ts +7 -0
- package/dist/templates/react-router/tsconfig.json +29 -0
- package/dist/templates/react-router/vite.config.ts +10 -0
- package/dist/templates/react-router-ai/README.md +172 -0
- package/dist/templates/react-router-ai/_gitignore +6 -0
- package/dist/templates/react-router-ai/app/components/puck-render.tsx +11 -0
- package/dist/templates/react-router-ai/app/lib/pages.server.ts +29 -0
- package/dist/templates/react-router-ai/app/lib/resolve-puck-path.server.ts +19 -0
- package/dist/templates/react-router-ai/app/root.tsx +65 -0
- package/dist/templates/react-router-ai/app/routes/_index.tsx +31 -0
- package/dist/templates/react-router-ai/app/routes/api.puck.ts +34 -0
- package/dist/templates/react-router-ai/app/routes/puck-splat.tsx +119 -0
- package/dist/templates/react-router-ai/app/routes.ts +8 -0
- package/dist/templates/react-router-ai/database.json +1 -0
- package/dist/templates/react-router-ai/package.json +35 -0
- package/dist/templates/react-router-ai/public/favicon.ico +0 -0
- package/dist/templates/react-router-ai/puck.config.tsx +25 -0
- package/dist/templates/react-router-ai/react-router.config.ts +7 -0
- package/dist/templates/react-router-ai/tsconfig.json +29 -0
- package/dist/templates/react-router-ai/vite.config.ts +10 -0
- package/dist/templates/tanstack-start/README.md +113 -0
- package/dist/templates/tanstack-start/_gitignore +12 -0
- package/dist/templates/tanstack-start/database.json +1 -0
- package/dist/templates/tanstack-start/package.json +26 -0
- package/dist/templates/tanstack-start/puck.config.tsx +23 -0
- package/dist/templates/tanstack-start/src/components/puck-render.tsx +8 -0
- package/dist/templates/tanstack-start/src/lib/pages.server.ts +26 -0
- package/dist/templates/tanstack-start/src/lib/pages.ts +39 -0
- package/dist/templates/tanstack-start/src/lib/resolve-puck-path.ts +19 -0
- package/dist/templates/tanstack-start/src/routeTree.gen.ts +86 -0
- package/dist/templates/tanstack-start/src/router.tsx +19 -0
- package/dist/templates/tanstack-start/src/routes/$.tsx +41 -0
- package/dist/templates/tanstack-start/src/routes/__root.tsx +42 -0
- package/dist/templates/tanstack-start/src/routes/index.tsx +18 -0
- package/dist/templates/tanstack-start/src/styles.css +13 -0
- package/dist/templates/tanstack-start/tsconfig.json +24 -0
- package/dist/templates/tanstack-start/vite.config.ts +15 -0
- package/dist/templates/tanstack-start-ai/README.md +171 -0
- package/dist/templates/tanstack-start-ai/_gitignore +12 -0
- package/dist/templates/tanstack-start-ai/database.json +1 -0
- package/dist/templates/tanstack-start-ai/package.json +28 -0
- package/dist/templates/tanstack-start-ai/puck.config.tsx +23 -0
- package/dist/templates/tanstack-start-ai/src/components/puck-render.tsx +11 -0
- package/dist/templates/tanstack-start-ai/src/lib/pages.server.ts +26 -0
- package/dist/templates/tanstack-start-ai/src/lib/pages.ts +39 -0
- package/dist/templates/tanstack-start-ai/src/lib/resolve-puck-path.ts +19 -0
- package/dist/templates/tanstack-start-ai/src/routeTree.gen.ts +104 -0
- package/dist/templates/tanstack-start-ai/src/router.tsx +19 -0
- package/dist/templates/tanstack-start-ai/src/routes/$.tsx +73 -0
- package/dist/templates/tanstack-start-ai/src/routes/__root.tsx +42 -0
- package/dist/templates/tanstack-start-ai/src/routes/api/puck/$.ts +39 -0
- package/dist/templates/tanstack-start-ai/src/routes/index.tsx +18 -0
- package/dist/templates/tanstack-start-ai/src/styles.css +13 -0
- package/dist/templates/tanstack-start-ai/tsconfig.json +24 -0
- package/dist/templates/tanstack-start-ai/vite.config.ts +15 -0
- package/dist/templates/vinext/README.md +112 -0
- package/dist/templates/vinext/_gitignore +33 -0
- package/dist/templates/vinext/app/[...puckPath]/client.tsx +9 -0
- package/dist/templates/vinext/app/[...puckPath]/page.tsx +49 -0
- package/dist/templates/vinext/app/favicon.ico +0 -0
- package/dist/templates/vinext/app/layout.tsx +13 -0
- package/dist/templates/vinext/app/page.tsx +1 -0
- package/dist/templates/vinext/app/puck/[...puckPath]/client.tsx +20 -0
- package/dist/templates/vinext/app/puck/[...puckPath]/page.tsx +55 -0
- package/dist/templates/vinext/app/puck/api/route.ts +25 -0
- package/dist/templates/vinext/app/puck/page.tsx +3 -0
- package/dist/templates/vinext/app/styles.css +3 -0
- package/dist/templates/vinext/database.json +1 -0
- package/dist/templates/vinext/lib/get-page.ts +11 -0
- package/dist/templates/vinext/package.json +30 -0
- package/dist/templates/vinext/proxy.ts +27 -0
- package/dist/templates/vinext/puck.config.tsx +25 -0
- package/dist/templates/vinext/tsconfig.json +30 -0
- package/dist/templates/vinext/vite.config.ts +6 -0
- package/dist/templates/vinext-ai/README.md +169 -0
- package/dist/templates/vinext-ai/_gitignore +33 -0
- package/dist/templates/vinext-ai/app/[...puckPath]/client.tsx +12 -0
- package/dist/templates/vinext-ai/app/[...puckPath]/page.tsx +49 -0
- package/dist/templates/vinext-ai/app/api/pages/route.ts +26 -0
- package/dist/templates/vinext-ai/app/api/puck/[...all]/route.ts +31 -0
- package/dist/templates/vinext-ai/app/layout.tsx +13 -0
- package/dist/templates/vinext-ai/app/page.tsx +1 -0
- package/dist/templates/vinext-ai/app/puck/[...puckPath]/client.tsx +38 -0
- package/dist/templates/vinext-ai/app/puck/[...puckPath]/page.tsx +57 -0
- package/dist/templates/vinext-ai/app/puck/page.tsx +3 -0
- package/dist/templates/vinext-ai/app/styles.css +3 -0
- package/dist/templates/vinext-ai/database.json +1 -0
- package/dist/templates/vinext-ai/lib/get-page.ts +11 -0
- package/dist/templates/vinext-ai/package.json +32 -0
- package/dist/templates/vinext-ai/proxy.ts +27 -0
- package/dist/templates/vinext-ai/public/favicon.ico +0 -0
- package/dist/templates/vinext-ai/puck.config.tsx +25 -0
- package/dist/templates/vinext-ai/tsconfig.json +30 -0
- package/dist/templates/vinext-ai/vite.config.ts +9 -0
- package/dist/templates/vite/README.md +56 -0
- package/dist/templates/vite/_gitignore +24 -0
- package/dist/templates/vite/database.json +1 -0
- package/dist/templates/vite/index.html +12 -0
- package/dist/templates/vite/package.json +29 -0
- package/dist/templates/vite/server/index.ts +13 -0
- package/dist/templates/vite/server/prod.ts +18 -0
- package/dist/templates/vite/server/puck/pages.ts +32 -0
- package/dist/templates/vite/src/App.tsx +11 -0
- package/dist/templates/vite/src/main.tsx +12 -0
- package/dist/templates/vite/src/puck/editor.tsx +28 -0
- package/dist/templates/vite/src/puck/page.tsx +27 -0
- package/dist/templates/vite/src/puck/pages.ts +15 -0
- package/dist/templates/vite/src/puck/root.tsx +27 -0
- package/dist/templates/vite/src/puck.config.tsx +23 -0
- package/dist/templates/vite/tsconfig.app.json +26 -0
- package/dist/templates/vite/tsconfig.json +7 -0
- package/dist/templates/vite/tsconfig.node.json +23 -0
- package/dist/templates/vite/vite.config.ts +14 -0
- package/dist/templates/vite-ai/README.md +67 -0
- package/dist/templates/vite-ai/_gitignore +24 -0
- package/dist/templates/vite-ai/database.json +1 -0
- package/dist/templates/vite-ai/index.html +12 -0
- package/dist/templates/vite-ai/package.json +31 -0
- package/dist/templates/vite-ai/server/index.ts +15 -0
- package/dist/templates/vite-ai/server/prod.ts +18 -0
- package/dist/templates/vite-ai/server/puck/cloud.ts +30 -0
- package/dist/templates/vite-ai/server/puck/pages.ts +32 -0
- package/dist/templates/vite-ai/src/App.tsx +11 -0
- package/dist/templates/vite-ai/src/main.tsx +12 -0
- package/dist/templates/vite-ai/src/puck/editor.tsx +49 -0
- package/dist/templates/vite-ai/src/puck/page.tsx +28 -0
- package/dist/templates/vite-ai/src/puck/pages.ts +15 -0
- package/dist/templates/vite-ai/src/puck/root.tsx +27 -0
- package/dist/templates/vite-ai/src/puck.config.tsx +23 -0
- package/dist/templates/vite-ai/tsconfig.app.json +26 -0
- package/dist/templates/vite-ai/tsconfig.json +7 -0
- package/dist/templates/vite-ai/tsconfig.node.json +23 -0
- package/dist/templates/vite-ai/vite.config.ts +14 -0
- package/package.json +52 -0
package/dist/docs/cli.md
ADDED
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
# CLI
|
|
2
|
+
|
|
3
|
+
The Puck CLI sets up Puck and [Puck Cloud](https://cloud.puckeditor.com) in a new or existing app. It's built for coding agents, and works interactively for humans.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npx @puckeditor/cli init
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
`init` inspects your project and makes the smallest set of changes needed to reach a working Puck app, with Puck AI if you choose it:
|
|
10
|
+
|
|
11
|
+
- **No app yet**: creates a Next.js, React Router, TanStack Start, vinext, Vite or Astro app, or a Hono or Express server, from the Puck [recipes](https://github.com/puckeditor/puck#recipes)
|
|
12
|
+
- **App without Puck**: installs `@puckeditor/core` and adds an editor at `/edit`
|
|
13
|
+
- **Puck without Puck AI** (when you choose it): installs `@puckeditor/cloud-client` and `@puckeditor/plugin-ai`, adds the `/api/puck` route and the Puck AI plugin, and connects your Puck Cloud account
|
|
14
|
+
- **Already set up**: verifies the setup and changes nothing
|
|
15
|
+
|
|
16
|
+
With Puck AI, the only manual step is logging in to Puck Cloud and approving the connection in your browser. When it's done, the CLI starts your dev server and opens the editor.
|
|
17
|
+
|
|
18
|
+
Puck AI, [Puck Pages](#puck-pages) and [Puck Auth](#puck-auth) are optional. Each uses Puck Cloud, so choosing any of them sets up Puck Cloud too. `init` asks which to include, with all three selected. To choose up front, pass `--ai`, `--pages` or `--auth` to include only those, `--no-ai`, `--no-pages` or `--no-auth` to include all but those, or `--editor-only` for none.
|
|
19
|
+
|
|
20
|
+
## Supported projects
|
|
21
|
+
|
|
22
|
+
- Next.js 15+ using the App Router (`app/` or `src/app/`)
|
|
23
|
+
- React Router 7+ in framework mode. New apps use React Router 8, or React Router 7 on Node.js older than 22.22, which React Router 8 requires
|
|
24
|
+
- [TanStack Start](https://tanstack.com/start) 1.132+
|
|
25
|
+
- [vinext](https://github.com/cloudflare/vinext) 1+ using the App Router
|
|
26
|
+
- [Vite](https://vite.dev) 6+ React apps (see [Vite and Astro](#vite-and-astro))
|
|
27
|
+
- [Astro](https://astro.build) 7+ (see [Vite and Astro](#vite-and-astro))
|
|
28
|
+
- [Hono](https://hono.dev) 4+ and [Express](https://expressjs.com) 4.16+ servers (see [Servers](#servers))
|
|
29
|
+
- npm, pnpm, Yarn and Bun, including workspaces
|
|
30
|
+
- TypeScript projects
|
|
31
|
+
|
|
32
|
+
Run `npx @puckeditor/cli frameworks` to see what the CLI sets up for each framework. Older versions fail with `PUCK-CLI-UNSUPPORTED-FRAMEWORK-VERSION`.
|
|
33
|
+
|
|
34
|
+
When the CLI can't safely change something, like an existing `middleware.ts`, it leaves the file alone and tells you exactly what to add.
|
|
35
|
+
|
|
36
|
+
## Vite and Astro
|
|
37
|
+
|
|
38
|
+
A Vite app, or an Astro site without a server adapter, has nowhere to save pages or run Puck Cloud. The CLI asks where that server comes from. Agents get a `choose_backend` action; pass `--backend` to choose up front:
|
|
39
|
+
|
|
40
|
+
- `--backend add`: in Vite, adds a Hono server in `server/`, run by Vite in development with `@hono/vite-dev-server` and by `npm start` in production. In Astro, runs `astro add node` so pages and API routes are served on demand
|
|
41
|
+
- `--backend external --backend-url <url>`: proxies `/api` to a server that runs elsewhere, e.g. a [Hono or Express server](#servers) set up by the CLI. Puck Cloud and `PUCK_API_KEY` live on that server
|
|
42
|
+
- `--backend none`: saves pages in the browser's `localStorage`. Puck AI isn't available without a server
|
|
43
|
+
|
|
44
|
+
In Vite, the editor opens at any URL ending in `/edit`: `<PuckRoot>` wraps your app in `src/main.tsx` and renders the editor instead. Render published pages with `<PuckPage path={...} />` wherever your app renders pages.
|
|
45
|
+
|
|
46
|
+
In Astro with an adapter, `src/pages/[...puckPath].astro` renders the editor at `/edit` URLs and published pages everywhere else, on the server. Without one, the editor is a static page at `/edit?path=/your/page`. The CLI runs `astro add react` when React isn't set up yet.
|
|
47
|
+
|
|
48
|
+
## Servers
|
|
49
|
+
|
|
50
|
+
In a Hono or Express project, the CLI sets up the APIs a Puck editor in another app talks to:
|
|
51
|
+
|
|
52
|
+
- `/api/pages`: loads (`GET ?path=/about`) and saves (`POST { path, data }`) pages, in `src/puck/pages.ts`
|
|
53
|
+
- `/api/puck/*`: the Puck Cloud route for Puck AI, in `src/puck/cloud.ts`, when you choose Puck AI
|
|
54
|
+
|
|
55
|
+
With [Puck Pages](#puck-pages), `/api/pages` serves pages published in Puck Cloud instead, and only loads them.
|
|
56
|
+
|
|
57
|
+
It mounts both on your app before it starts serving, so your own middleware runs first. Node doesn't load `.env` files, so the CLI adds `--env-file-if-exists=.env.local` to a `tsx` or `node` dev script. Bun loads `.env.local` itself. On Cloudflare Workers, put `PUCK_API_KEY` in `.dev.vars` instead.
|
|
58
|
+
|
|
59
|
+
Add the Puck AI plugin in the app with the editor. If that app runs on another origin, proxy `/api` to the server in development, or pass `host` to `createAiPlugin`.
|
|
60
|
+
|
|
61
|
+
## For coding agents
|
|
62
|
+
|
|
63
|
+
Run with `--yes --json`. The CLI never prompts, and prints exactly one JSON document to stdout.
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
npx @puckeditor/cli init --yes --json
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
When `status` is `action_required`, nothing has been changed yet. Show each entry in `actions` to the developer, then run its `rerun` command. Without any of those flags, the first run returns a `choose_capabilities` action, so the developer can choose which of Puck AI, Puck Pages and Puck Auth to add. With `--ai`, the first run asks the developer to log in:
|
|
70
|
+
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"status": "action_required",
|
|
74
|
+
"message": "Puck Cloud login required. No changes have been made yet.",
|
|
75
|
+
"actions": [
|
|
76
|
+
{
|
|
77
|
+
"type": "browser_login",
|
|
78
|
+
"url": "https://cloud.puckeditor.com/cli/connect#code=BCDF-GHJK",
|
|
79
|
+
"userCode": "BCDF-GHJK",
|
|
80
|
+
"rerun": "npx @puckeditor/cli init --yes --json --ai"
|
|
81
|
+
}
|
|
82
|
+
]
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
After the developer approves, the same command completes the setup:
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"status": "success",
|
|
91
|
+
"project": { "framework": "next", "packageManager": "pnpm" },
|
|
92
|
+
"puck": { "installed": true, "configured": true },
|
|
93
|
+
"cloud": { "configured": true, "verified": "remote" },
|
|
94
|
+
"ai": { "installed": true, "configured": true },
|
|
95
|
+
"filesModified": [".env.local", "app/api/puck/[...all]/route.ts"]
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Start with `npx @puckeditor/cli status --json` to see what's already set up and which command to run next.
|
|
100
|
+
|
|
101
|
+
### Statuses
|
|
102
|
+
|
|
103
|
+
| Status | Meaning |
|
|
104
|
+
| ----------------- | --------------------------------------------------------------------------------------- |
|
|
105
|
+
| `success` | The project is set up. `changed` is `false` if there was nothing to do. |
|
|
106
|
+
| `action_required` | Input or approval is needed. Nothing was changed. Complete `actions`, then run `rerun`. |
|
|
107
|
+
| `partial` | Changes were applied, but some `actions` must be completed by hand. |
|
|
108
|
+
| `error` | Something went wrong. See `error.code` and `error.message`. |
|
|
109
|
+
|
|
110
|
+
### Actions
|
|
111
|
+
|
|
112
|
+
| Type | What to do |
|
|
113
|
+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
|
114
|
+
| `browser_login` | Ask the developer to open `url`, confirm `userCode` and approve |
|
|
115
|
+
| `provide_api_key` | Ask for a Puck API key, then re-run with `PUCK_API_KEY` set |
|
|
116
|
+
| `confirm_plan` | Review `plan.steps`, then re-run with `--yes` |
|
|
117
|
+
| `choose_capabilities` | Ask the developer which of `choices` to add, then re-run `init` with each one's flag, or `none` (`--editor-only`) for none |
|
|
118
|
+
| `choose_backend` | Ask the developer, then re-run with `--backend add`, `--backend external --backend-url <url>` or `--backend none` |
|
|
119
|
+
| `choose_framework` | Re-run `init` with `--framework` and one of `next`, `react-router`, `tanstack-start`, `vinext`, `vite`, `astro`, `hono` or `express` |
|
|
120
|
+
| `provide_app_name` | Re-run `init` with `--name <name>` |
|
|
121
|
+
| `choose_workspace_package` | Re-run with `--workspace <dir>` for one of `choices` |
|
|
122
|
+
| `manual_edit` | Apply `snippet` to `file` as described in `instructions` |
|
|
123
|
+
| `set_environment_variable` | Set `PUCK_API_KEY` wherever the app runs |
|
|
124
|
+
|
|
125
|
+
### Exit codes
|
|
126
|
+
|
|
127
|
+
| Code | Meaning |
|
|
128
|
+
| ---- | ----------------------------------------------- |
|
|
129
|
+
| 0 | Success |
|
|
130
|
+
| 2 | Invalid arguments or API key |
|
|
131
|
+
| 3 | Unsupported or ambiguous project |
|
|
132
|
+
| 4 | File conflict |
|
|
133
|
+
| 5 | Package manager failure |
|
|
134
|
+
| 6 | `doctor` found problems |
|
|
135
|
+
| 7 | Puck Cloud couldn't complete a login or request |
|
|
136
|
+
| 10 | Action required |
|
|
137
|
+
| 11 | Partially set up |
|
|
138
|
+
|
|
139
|
+
### Reading the docs
|
|
140
|
+
|
|
141
|
+
The CLI includes these docs as markdown, matching its release. Use the version of the CLI that matches the project's `@puckeditor/core`:
|
|
142
|
+
|
|
143
|
+
```sh
|
|
144
|
+
npx @puckeditor/cli docs ls # every page
|
|
145
|
+
npx @puckeditor/cli docs find "dynamic fields" # find pages by title or heading
|
|
146
|
+
npx @puckeditor/cli docs grep resolveData # search page content
|
|
147
|
+
npx @puckeditor/cli docs cat api-reference/fields/text
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
The latest docs are indexed at [llms.txt](https://puckeditor.com/llms.txt), and any page is available as markdown by adding `.md` to its URL. Agents with skill support can also install the [Puck skill](https://github.com/puckeditor/skills):
|
|
151
|
+
|
|
152
|
+
```sh
|
|
153
|
+
npx skills add puckeditor/skills --skill puck
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## Commands
|
|
157
|
+
|
|
158
|
+
| Command | Description |
|
|
159
|
+
| --------------------- | ------------------------------------------------------------------------------ |
|
|
160
|
+
| `init` | Set up Puck, optionally with Puck AI, creating an app if needed |
|
|
161
|
+
| `add editor` | Add the Puck editor |
|
|
162
|
+
| `add cloud` | Connect Puck Cloud (adds the editor first if needed) |
|
|
163
|
+
| `add ai` | Add the Puck AI plugin (adds Puck Cloud first if needed) |
|
|
164
|
+
| `add pages` | Store and publish pages in Puck Cloud (adds Puck Cloud first if needed) |
|
|
165
|
+
| `add auth` | Require Sign in with Puck to edit (adds Puck Cloud first if needed) |
|
|
166
|
+
| `pages import <file>` | Publish pages from a JSON file to Puck Cloud |
|
|
167
|
+
| `connect [branch]` | Log in to Puck Cloud again and replace `PUCK_API_KEY`, optionally for a branch |
|
|
168
|
+
| `status` | Show what's installed and configured |
|
|
169
|
+
| `doctor` | Diagnose problems and suggest fixes. Never makes changes |
|
|
170
|
+
| `frameworks` | Show the supported frameworks and versions |
|
|
171
|
+
| `docs` | Read these docs: `ls`, `cat <page>`, `find <query>`, `grep <text>` |
|
|
172
|
+
| `telemetry` | Show or change anonymous usage data collection |
|
|
173
|
+
|
|
174
|
+
## Flags
|
|
175
|
+
|
|
176
|
+
| Flag | Description |
|
|
177
|
+
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
178
|
+
| `--json` | Machine-readable output |
|
|
179
|
+
| `--yes`, `-y` | Apply the plan without prompting |
|
|
180
|
+
| `--dry-run` | Show the plan without changing anything or logging in |
|
|
181
|
+
| `--cwd <path>` | Run against another directory |
|
|
182
|
+
| `--workspace <name\|dir>` | Choose an app when running from a monorepo root |
|
|
183
|
+
| `--api-key <key>` | Use an existing API key instead of logging in |
|
|
184
|
+
| `--no-env-write` | Don't write `PUCK_API_KEY` to a file |
|
|
185
|
+
| `--ai`, `--pages`, `--auth` | Include only these of Puck AI, [Puck Pages](#puck-pages) and [Puck Auth](#puck-auth) (`init`) |
|
|
186
|
+
| `--no-ai`, `--no-pages`, `--no-auth` | Include all of them except these (`init`) |
|
|
187
|
+
| `--editor-only` | Include none of them (`init`) |
|
|
188
|
+
| `--canary` | Install the latest canaries of `@puckeditor/core`, `cloud-client` and the plugins, pinned to exact versions (`init` and `add`). `PUCK_CANARY=1` does the same. Private packages are read with your npm login |
|
|
189
|
+
| `--backend <choice>` | Where a Vite app's server comes from: `add`, `external` or `none` |
|
|
190
|
+
| `--backend-url <url>` | The server for `--backend external` |
|
|
191
|
+
| `--wait` | Wait for login approval instead of returning `action_required` |
|
|
192
|
+
| `--framework <name>` | Framework for a new app: `next`, `react-router`, `tanstack-start`, `vinext`, `vite`, `astro`, `hono` or `express` |
|
|
193
|
+
| `--name <name>` | Directory for a new app |
|
|
194
|
+
| `--package-manager <name>` | Override the detected package manager |
|
|
195
|
+
| `--offline` | Skip the Puck Cloud connection check (`doctor`) |
|
|
196
|
+
|
|
197
|
+
## API keys
|
|
198
|
+
|
|
199
|
+
The CLI writes `PUCK_API_KEY` to `.env.local`, and makes sure it's ignored by git. If a key already exists in `.env.development.local`, it's updated there instead. Keys are never written to `.env`, and never printed.
|
|
200
|
+
|
|
201
|
+
To use an existing key, prefer the environment over `--api-key`, which is visible in your shell history:
|
|
202
|
+
|
|
203
|
+
```sh
|
|
204
|
+
PUCK_API_KEY=your-key npx @puckeditor/cli add cloud --yes
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
To log in again, for example to replace a revoked key, run `connect`. It always starts a new login and replaces the existing key, without changing any code:
|
|
208
|
+
|
|
209
|
+
```sh
|
|
210
|
+
npx @puckeditor/cli connect
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Each key is for one branch of a Puck Cloud project. When you approve the login, you choose the project and branch, which defaults to the project's default branch. To connect to another branch, for example for a preview deployment, name it:
|
|
214
|
+
|
|
215
|
+
```sh
|
|
216
|
+
npx @puckeditor/cli connect feature/new-hero
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Puck Cloud preselects that branch, or offers to create it from the default branch.
|
|
220
|
+
|
|
221
|
+
Remember to set `PUCK_API_KEY` in your production environment too. `react-router-serve` and Cloudflare Workers don't load `.env` files; on Workers, use `wrangler secret put PUCK_API_KEY`.
|
|
222
|
+
|
|
223
|
+
The `/api/puck` route and the editor are public by default. Add [Puck Auth](#puck-auth), or your own authentication, before deploying.
|
|
224
|
+
|
|
225
|
+
## Puck AI
|
|
226
|
+
|
|
227
|
+
`init` and `add ai` add the Puck AI plugin to the editor, allow design mode in the `/api/puck` route, and wrap your config with `withDynamicConfig` so components designed by Puck AI render on your pages. If your editor has been customised, the CLI leaves it alone and prints the code to add.
|
|
228
|
+
|
|
229
|
+
## Puck Pages
|
|
230
|
+
|
|
231
|
+
`add pages`, or `init --pages`, stores pages in Puck Cloud with the [Pages plugin](https://puckeditor.com/docs/pages/overview), which adds page management, drafts, publishing and version history to the editor:
|
|
232
|
+
|
|
233
|
+
- The editor opens at `/puck`, with the page to edit in the `path` query parameter, e.g. `/puck?path=/about`. URLs ending in `/edit` redirect there
|
|
234
|
+
- Published pages are rendered from Puck Cloud with `getPage` from `@puckeditor/cloud-client`. In Vite apps and on [servers](#servers), `/api/pages` serves them read-only
|
|
235
|
+
- `@puckeditor/cloud-client` is updated to a version with Puck Pages, and the `/api/puck` route gets the `authenticate` option it requires
|
|
236
|
+
|
|
237
|
+
Pages in `database.json`, or wherever your app saved them, aren't moved automatically. Import them with `pages import`, then delete the old routes.
|
|
238
|
+
|
|
239
|
+
Until you add [Puck Auth](#puck-auth), anyone who can reach `/api/puck` can edit, publish and delete pages using your API key.
|
|
240
|
+
|
|
241
|
+
### Importing pages
|
|
242
|
+
|
|
243
|
+
```sh
|
|
244
|
+
npx @puckeditor/cli pages import database.json
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
`pages import` publishes a JSON object of Puck data keyed by route, like a recipe's `database.json`. Pages that already exist in Puck Cloud are kept. It uses `--api-key`, `PUCK_API_KEY` in the environment, or the key in the env files where it runs, so run it from your app. The API key decides which project and branch the pages go to.
|
|
248
|
+
|
|
249
|
+
Agents pass `--yes --json`. If Puck Cloud fails part way, the status is `partial` and `pagesImport.notImported` lists the routes left. Run the command again to import them.
|
|
250
|
+
|
|
251
|
+
## Puck Auth
|
|
252
|
+
|
|
253
|
+
`add auth`, or `init --auth`, requires [Sign in with Puck](https://puckeditor.com/docs/auth/overview) to edit:
|
|
254
|
+
|
|
255
|
+
- The `/api/puck` route passes `authenticate` from `@puckeditor/cloud-client/auth` to `puckHandler`, which serves the sign-in routes under `/api/puck/auth` and rejects requests from anyone not signed in to your Puck Cloud organization
|
|
256
|
+
- The editor sends signed-out visitors to sign in. Server-rendered apps check before rendering it. Vite apps, and Astro sites without a server, check in the browser with `<RequireSession>`
|
|
257
|
+
- The Puck Auth plugin adds an account menu to the editor
|
|
258
|
+
|
|
259
|
+
Without Puck Pages, the editor still saves pages through your own route, which Sign in with Puck doesn't protect. On a Hono or Express server, `add auth` only changes the Cloud route, so run it in the editor's app too.
|
|
260
|
+
|
|
261
|
+
Members sign in to the API key's project and edit its branch. Set `PUCK_API_KEY` on each deployment to a key for the branch it should edit, so a preview deployment can't edit production.
|
|
262
|
+
|
|
263
|
+
## Telemetry
|
|
264
|
+
|
|
265
|
+
The CLI collects anonymous usage data to help us improve it. The first time it runs without `--json`, it prints a notice.
|
|
266
|
+
|
|
267
|
+
Each command sends one event to Puck Cloud with:
|
|
268
|
+
|
|
269
|
+
- The command, what `add` was asked for, the result status, error and warning codes, the actions it returned, the exit code and how long it took
|
|
270
|
+
- Whether it was a dry run, made changes, ran interactively, used `--json` or ran in CI
|
|
271
|
+
- The CLI version, operating system, CPU architecture and Node.js version
|
|
272
|
+
- The name of the coding agent running it, if it's a known one, such as `claude-code`
|
|
273
|
+
- The framework and its major version, the package manager, the `--backend` choice, whether the project is in a monorepo, and whether the Puck editor, Puck Cloud and Puck AI are set up
|
|
274
|
+
- A random ID, stored in `~/.config/puck/telemetry.json`
|
|
275
|
+
|
|
276
|
+
It never sends code, file paths, project or package names, hostnames, error messages, flag values or API keys. When you log in to Puck Cloud with `connect`, the random ID is linked to your account.
|
|
277
|
+
|
|
278
|
+
To turn telemetry off, run:
|
|
279
|
+
|
|
280
|
+
```sh
|
|
281
|
+
npx @puckeditor/cli telemetry disable
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Or set `PUCK_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1` in your environment. `telemetry status` shows whether it's on, and `PUCK_TELEMETRY_DEBUG=1` prints each event instead of sending it.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Composition
|
|
2
|
+
|
|
3
|
+
Puck uses compositional patterns enable completely custom editor interfaces. [See an example](https://demo.puckeditor.com/custom-ui/edit/).
|
|
4
|
+
|
|
5
|
+
## Using composition
|
|
6
|
+
|
|
7
|
+
Composition can be achieved by providing [`children`](/docs/api-reference/components/puck#children) to the [`<Puck>` component](/docs/api-reference/components/puck):
|
|
8
|
+
|
|
9
|
+
```tsx
|
|
10
|
+
import { Puck } from "@puckeditor/core";
|
|
11
|
+
|
|
12
|
+
export function Editor() {
|
|
13
|
+
return (
|
|
14
|
+
<Puck>
|
|
15
|
+
<div
|
|
16
|
+
style={{ display: "grid", gridTemplateColumns: "1fr 2fr", gridGap: 16 }}
|
|
17
|
+
>
|
|
18
|
+
<div>
|
|
19
|
+
{/* Render the drag-and-drop preview */}
|
|
20
|
+
<Puck.Preview />
|
|
21
|
+
</div>
|
|
22
|
+
<div>
|
|
23
|
+
{/* Render the component list */}
|
|
24
|
+
<Puck.Components />
|
|
25
|
+
</div>
|
|
26
|
+
</div>
|
|
27
|
+
</Puck>
|
|
28
|
+
);
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Compositional components
|
|
33
|
+
|
|
34
|
+
Puck exposes its core components, allowing you to compose them together to create new layouts:
|
|
35
|
+
|
|
36
|
+
- [`<Puck.Components>`](/docs/api-reference/components/puck-components) - A draggable list of components.
|
|
37
|
+
- [`<Puck.Fields>`](/docs/api-reference/components/puck-fields) - The fields for the currently selected item.
|
|
38
|
+
- [`<Puck.Outline>`](/docs/api-reference/components/puck-outline) - An interactive outline.
|
|
39
|
+
- [`<Puck.Preview>`](/docs/api-reference/components/puck-preview) - A drag-and-drop preview.
|
|
40
|
+
|
|
41
|
+
The internal UI for these components can also be changed by implementing [UI overrides](/docs/extending-puck/ui-overrides) or [theming](/docs/extending-puck/theming).
|
|
42
|
+
|
|
43
|
+
### Helper components
|
|
44
|
+
|
|
45
|
+
Puck also exposes helper components for even deeper customization:
|
|
46
|
+
|
|
47
|
+
- [`<Drawer>`](/docs/api-reference/components/drawer) - A reference list of items that can be dragged into a droppable area, normally `<Puck.Preview>`.
|
|
48
|
+
- [`<Drawer.Item>`](/docs/api-reference/components/drawer-item) - An item that can be dragged from a `<Drawer>`.
|
|
49
|
+
- [`<FieldLabel>`](/docs/api-reference/components/field-label) - A styled label for creating inputs.
|
|
50
|
+
|
|
51
|
+
## Further reading
|
|
52
|
+
|
|
53
|
+
- [Internal Puck API](/docs/extending-puck/internal-puck-api)
|
|
54
|
+
- [UI overrides](/docs/extending-puck/ui-overrides)
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# Custom Fields
|
|
2
|
+
|
|
3
|
+
Puck can be extended with completely custom fields for different use-cases.
|
|
4
|
+
|
|
5
|
+
## Creating a custom field
|
|
6
|
+
|
|
7
|
+
Creating a custom field is possible using the [`custom` field type](/docs/api-reference/fields/custom):
|
|
8
|
+
|
|
9
|
+
```tsx
|
|
10
|
+
const config = {
|
|
11
|
+
components: {
|
|
12
|
+
Example: {
|
|
13
|
+
fields: {
|
|
14
|
+
title: {
|
|
15
|
+
type: "custom",
|
|
16
|
+
render: ({ name, onChange, value }) => (
|
|
17
|
+
<input
|
|
18
|
+
defaultValue={value}
|
|
19
|
+
name={name}
|
|
20
|
+
onChange={(e) => onChange(e.currentTarget.value)}
|
|
21
|
+
style={{ border: "1px solid black", padding: 4 }}
|
|
22
|
+
/>
|
|
23
|
+
),
|
|
24
|
+
},
|
|
25
|
+
},
|
|
26
|
+
render: ({ title }) => {
|
|
27
|
+
return <p>{title}</p>;
|
|
28
|
+
},
|
|
29
|
+
},
|
|
30
|
+
},
|
|
31
|
+
};
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The [`onChange` function](/docs/api-reference/fields/custom#onchangevalue-ui) updates the Puck data payload for the field name, in this case "title".
|
|
35
|
+
|
|
36
|
+
## Adding a label
|
|
37
|
+
|
|
38
|
+
You can add your own label, but it's recommended to use the [`<FieldLabel>` component](/docs/api-reference/components/field-label) provided by Puck to seamlessly integrate into the Puck field UI.
|
|
39
|
+
|
|
40
|
+
```tsx
|
|
41
|
+
import { FieldLabel } from "@puckeditor/core";
|
|
42
|
+
|
|
43
|
+
const config = {
|
|
44
|
+
components: {
|
|
45
|
+
Example: {
|
|
46
|
+
fields: {
|
|
47
|
+
title: {
|
|
48
|
+
type: "custom",
|
|
49
|
+
label: "Label Example",
|
|
50
|
+
render: ({ field }) => (
|
|
51
|
+
<FieldLabel label={field.label}>
|
|
52
|
+
<input {/*...*/} />
|
|
53
|
+
</FieldLabel>
|
|
54
|
+
),
|
|
55
|
+
},
|
|
56
|
+
},
|
|
57
|
+
// ...
|
|
58
|
+
},
|
|
59
|
+
},
|
|
60
|
+
};
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Rendering Puck fields internally
|
|
64
|
+
|
|
65
|
+
Use the [`<AutoField>` component](/docs/api-reference/components/auto-field) to render Puck fields within your custom field.
|
|
66
|
+
|
|
67
|
+
```tsx
|
|
68
|
+
import { AutoField } from "@puckeditor/core";
|
|
69
|
+
|
|
70
|
+
const config = {
|
|
71
|
+
components: {
|
|
72
|
+
Example: {
|
|
73
|
+
fields: {
|
|
74
|
+
title: {
|
|
75
|
+
type: "custom",
|
|
76
|
+
label: "Label Example",
|
|
77
|
+
render: ({ field, value, onChange }) => (
|
|
78
|
+
<FieldLabel label={field.label}>
|
|
79
|
+
<AutoField
|
|
80
|
+
field={{ type: "text" }}
|
|
81
|
+
onChange={(value) => onChange(value)}
|
|
82
|
+
value={value}
|
|
83
|
+
/>
|
|
84
|
+
</FieldLabel>
|
|
85
|
+
),
|
|
86
|
+
},
|
|
87
|
+
// ...
|
|
88
|
+
},
|
|
89
|
+
},
|
|
90
|
+
},
|
|
91
|
+
};
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Updating the UI state
|
|
95
|
+
|
|
96
|
+
The [`onChange` function](/docs/api-reference/fields/custom#onchangevalue-ui) can also be used to modify the [Puck UI state](/docs/api-reference/data-model/app-state#ui) at the same time as updating the field value:
|
|
97
|
+
|
|
98
|
+
```tsx
|
|
99
|
+
const config = {
|
|
100
|
+
components: {
|
|
101
|
+
Example: {
|
|
102
|
+
fields: {
|
|
103
|
+
title: {
|
|
104
|
+
type: "custom",
|
|
105
|
+
render: ({ name, onChange, value }) => (
|
|
106
|
+
<input
|
|
107
|
+
defaultValue={value}
|
|
108
|
+
name={name}
|
|
109
|
+
onChange={(e) =>
|
|
110
|
+
onChange(
|
|
111
|
+
e.currentTarget.value,
|
|
112
|
+
// Close the left side bar when this field is changed
|
|
113
|
+
{ leftSideBarVisible: false }
|
|
114
|
+
)
|
|
115
|
+
}
|
|
116
|
+
style={{ border: "1px solid black", padding: 4 }}
|
|
117
|
+
/>
|
|
118
|
+
),
|
|
119
|
+
},
|
|
120
|
+
},
|
|
121
|
+
render: ({ title }) => {
|
|
122
|
+
return <p>{title}</p>;
|
|
123
|
+
},
|
|
124
|
+
},
|
|
125
|
+
},
|
|
126
|
+
};
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Further reading
|
|
130
|
+
|
|
131
|
+
- [The `<AutoField>` API reference](/docs/api-reference/components/auto-field)
|
|
132
|
+
- [The `<FieldLabel>` API reference](/docs/api-reference/components/field-label)
|
|
133
|
+
- [The `custom` field API reference](/docs/api-reference/fields/custom)
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Field Transforms
|
|
2
|
+
|
|
3
|
+
Puck lets you modify props before rendering in the editor via the [`FieldTransforms` API](/docs/api-reference/field-transforms).
|
|
4
|
+
|
|
5
|
+
Use this API to implement custom rendering behavior for specific field types, which can be used to implement features such as inline text editing.
|
|
6
|
+
|
|
7
|
+
> **Note:** Field transforms only apply to components rendered in `<Puck>` and will not be applied to `<Render>`.
|
|
8
|
+
|
|
9
|
+
## Implementing a transform
|
|
10
|
+
|
|
11
|
+
Specify a transforms object for the fields you want to modify before rendering:
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
const fieldTransforms = {
|
|
15
|
+
text: ({ value }) => value.toUpperCase(), // Transform text fields to uppercase
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
const Example = () => <Puck fieldTransforms={fieldTransforms} />;
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Making it interactive
|
|
22
|
+
|
|
23
|
+
Combine transforms with [Overlay Portals](/docs/integrating-puck/overlay-portals) to make them interactive.
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
import { registerOverlayPortal } from "@puckeditor/core";
|
|
27
|
+
|
|
28
|
+
const EditableText = ({ value }) => {
|
|
29
|
+
const ref = useRef(null);
|
|
30
|
+
|
|
31
|
+
useEffect(() => {
|
|
32
|
+
if (ref.current) {
|
|
33
|
+
// Register the element as an overlay portal
|
|
34
|
+
registerOverlayPortal(ref.current);
|
|
35
|
+
}
|
|
36
|
+
}, [ref.current]);
|
|
37
|
+
|
|
38
|
+
return (
|
|
39
|
+
// Mark the element as editable for inline text editing
|
|
40
|
+
<p ref={ref} contentEditable>
|
|
41
|
+
{value}
|
|
42
|
+
</p>
|
|
43
|
+
);
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
const fieldTransforms = {
|
|
47
|
+
text: (props) => <EditableText {...props} />,
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
const Example = () => <Puck fieldTransforms={fieldTransforms} />;
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Because Puck calls transforms as functions, render components that use hooks from the transform instead of passing them directly.
|
|
54
|
+
|
|
55
|
+
## Define new fields
|
|
56
|
+
|
|
57
|
+
As with [field type overrides](/docs/extending-puck/ui-overrides#introducing-new-field-types), field transforms let you define your own field types:
|
|
58
|
+
|
|
59
|
+
```tsx
|
|
60
|
+
const fieldTransforms = {
|
|
61
|
+
example: () => <div />,
|
|
62
|
+
};
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Distributing field transforms as plugins
|
|
66
|
+
|
|
67
|
+
Distribute transforms as plugins to package up custom behavior.
|
|
68
|
+
|
|
69
|
+
```tsx
|
|
70
|
+
const plugin = {
|
|
71
|
+
fieldTransforms: {
|
|
72
|
+
example: ({ value }) => <div>{value}</div>, // Wrap all example fields with divs
|
|
73
|
+
},
|
|
74
|
+
|
|
75
|
+
// This example combines transforms with overrides
|
|
76
|
+
overrides: {
|
|
77
|
+
fieldTypes: {
|
|
78
|
+
example: () => <input />, // Define a field interface
|
|
79
|
+
},
|
|
80
|
+
},
|
|
81
|
+
};
|
|
82
|
+
|
|
83
|
+
const Example = () => <Puck plugins={[plugin]} />;
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Further reading
|
|
87
|
+
|
|
88
|
+
- [Field Transforms API reference](/docs/api-reference/field-transforms)
|
|
89
|
+
- [Overlay Portals API reference](/docs/integrating-puck/overlay-portals)
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Internal Puck API
|
|
2
|
+
|
|
3
|
+
Puck exposes its internal API as [`PuckApi`](/docs/api-reference/puck-api) for extending Puck with custom functionality within [custom fields](/docs/extending-puck/custom-fields), [compositional interfaces](/docs/extending-puck/composition) or [UI overrides](/docs/extending-puck/ui-overrides).
|
|
4
|
+
|
|
5
|
+
## Accessing the internal API
|
|
6
|
+
|
|
7
|
+
You can access [`PuckApi`](/docs/api-reference/puck-api) via two hooks:
|
|
8
|
+
|
|
9
|
+
- [`usePuck`](/docs/api-reference/functions/use-puck) - returns `PuckApi` as part of your component render lifecycle
|
|
10
|
+
- [`useGetPuck`](/docs/api-reference/functions/use-get-puck) - returns a function to access the latest `PuckApi` at call time
|
|
11
|
+
|
|
12
|
+
### Within the render lifecycle
|
|
13
|
+
|
|
14
|
+
To access the API within your render lifecycle, use the `usePuck` hook. You can use a selector to limit re-rendering to a specific part of the API.
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
import { createUsePuck } from "@puckeditor/core";
|
|
18
|
+
|
|
19
|
+
const usePuck = createUsePuck();
|
|
20
|
+
|
|
21
|
+
const Example = () => {
|
|
22
|
+
// Use a selector so you only re-render when the selected type changes
|
|
23
|
+
const type = usePuck((s) => s.selectedItem?.type || "Nothing");
|
|
24
|
+
|
|
25
|
+
return <h2>{type} selected</h2>;
|
|
26
|
+
};
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
See the [`usePuck`](/docs/api-reference/functions/use-puck) docs for a full API reference.
|
|
30
|
+
|
|
31
|
+
### Outside of the render lifecycle
|
|
32
|
+
|
|
33
|
+
Often it's not necessary to re-render your component when the PuckApi changes. Puck provides the `useGetPuck` hook for accessing the latest `PuckApi` at call time.
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
import { useGetPuck } from "@puckeditor/core";
|
|
37
|
+
|
|
38
|
+
const Example = () => {
|
|
39
|
+
const getPuck = useGetPuck();
|
|
40
|
+
|
|
41
|
+
const handleClick = useCallback(() => {
|
|
42
|
+
// Get the latest PuckApi value
|
|
43
|
+
const { appState } = getPuck();
|
|
44
|
+
|
|
45
|
+
console.log(appState);
|
|
46
|
+
}, [getPuck]);
|
|
47
|
+
|
|
48
|
+
return <button onClick={handleClick}>Click me</button>;
|
|
49
|
+
};
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
See the [`useGetPuck`](/docs/api-reference/functions/use-get-puck) docs for a full API reference.
|
|
53
|
+
|
|
54
|
+
## Usage in practice
|
|
55
|
+
|
|
56
|
+
Generally, you'll want to combine this with composition, UI overrides or custom fields.
|
|
57
|
+
|
|
58
|
+
Here's an example using the internal API to log the page data as JSON while retaining the standard Puck UI:
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
import { Puck, createUsePuck } from "@puckeditor/core";
|
|
62
|
+
|
|
63
|
+
const usePuck = createUsePuck();
|
|
64
|
+
|
|
65
|
+
const JSONLogger = ({ children }) => {
|
|
66
|
+
const appState = usePuck((s) => s.appState);
|
|
67
|
+
|
|
68
|
+
useEffect(() => {
|
|
69
|
+
console.log(appState);
|
|
70
|
+
}, [appState]);
|
|
71
|
+
|
|
72
|
+
return <>{children}</>;
|
|
73
|
+
};
|
|
74
|
+
|
|
75
|
+
export function Editor() {
|
|
76
|
+
return (
|
|
77
|
+
// Render the Puck context
|
|
78
|
+
<Puck>
|
|
79
|
+
<JSONLogger>
|
|
80
|
+
{/* Since we're overriding Puck's children, we restore the standard Puck UI */}
|
|
81
|
+
<Puck.Layout />
|
|
82
|
+
</JSONLogger>
|
|
83
|
+
</Puck>
|
|
84
|
+
);
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Further reading
|
|
89
|
+
|
|
90
|
+
- [`PuckApi` API reference](/docs/api-reference/puck-api)
|
|
91
|
+
- [`usePuck` API reference](/docs/api-reference/functions/use-puck)
|
|
92
|
+
- [`useGetPuck` API reference](/docs/api-reference/functions/use-get-puck)
|
|
93
|
+
- [`<Puck.Layout>` API reference](/docs/api-reference/components/puck-layout)
|
|
94
|
+
- [Composition](/docs/extending-puck/composition)
|
|
95
|
+
- [Custom fields](/docs/extending-puck/custom-fields)
|
|
96
|
+
- [UI overrides](/docs/extending-puck/ui-overrides)
|