Pagebuilder components — deploy into a project

This folder holds reference pagebuilder components and a script that copies them into a target htdocs tree. Use it when you want to add an existing component from refs into a project without overwriting files that are already there.

Where this must live in the project

install-in-project.sh assumes this directory is installed in node_modules:

<htdocs>/
  templates/
  resources/
  node_modules/
    @quatrecentquatre/
        front-end-tools/
            pagebuilder-components/    ← this folder (contains install-in-project.sh + component folders)
                install-in-project.sh
                block_example/
                    block_example.twig
                    assets/
                    modules/
                ...

The script sets the htdocs root to the parent of node_modules/, then copies files into templates/ and resources/ under that root.

If pagebuilder-components is not under htdocs/node_modules/, the destinations will be wrong. Package can be download by itself, placed wherever you want and adapt .sh script for path to fit the new emplacement. You can use .mdc files to run the same kind of behavior for installation with AI. (Command in AI chat : create component [COMPONENT_NAME])

Prerequisites

• A component folder named exactly as you will pass to the script (for example block_carousel, block_timeline).
• That folder must sit next to install-in-project.sh inside pagebuilder-components/.

Ignored names when listing “available components” in errors: [NOM_DU_COMPOSANT], commons, .DS_Store, and the script itself.

How to include a new component

1. Add or obtain the ref component under pagebuilder-components/<COMPONENT_NAME>/, with the structure your project expects (root Twig file(s), optional assets/, modules/, svg/, or other top-level folders). See create-pagebuilder-component.mdc in this repo for the full authoring convention.

2. From htdocs or the root folder where package.json is, run:

   npm run install-component -- COMPONENT_NAME

   Example:

   npm run install-component block_collapse

3. Read the script output. For each file it either copies, reports Copied …, or skips with Skipped (exists): … if the destination file already exists.

4. Finish integration in the project (the script only copies files). You may still need to:

   • Ajust files if you have to extend the section
   • Register the section in CMS / pagebuilder configuration
   • Import or wire SCSS/JS into the main bundles if your build does not pick up new files automatically
   • Commit the new files in the target project

What the script copies (and where)

| Source (under pagebuilder-components/<COMPONENT_NAME>/) | Destination (under htdocs) | | --------------------------------------------------------- | ---------------------------------------------------------- | | *.twig at component root | templates/partials/sections/pagebuilder/ (same filename) | | assets/js/** | resources/assets/js/** (relative paths preserved) | | assets/scss/*.scss (root of scss only) | resources/assets/scss/partials/sections/pagebuilder/ | | assets/scss/modules/**/*.scss | resources/assets/scss/partials/modules/** | | modules/** | templates/partials/modules/** | | svg/** | templates/partials/svg/** | | Any other top-level folder (e.g. commons/) | templates/partials/<folder-name>/** |

The assets/ folder is handled specially; everything else at the top level except root .twig files is expected to be a directory (modules, svg, commons, etc.).

Overwrites

Existing destination files are never replaced. If you need to refresh a file, remove or rename it in the project first, then run the script again—or copy/update manually.

Troubleshooting

• Ref folder does not exist: The name must match a directory beside the script. Use the exact folder name (often block_<something>).
• Files end up in the wrong place: Confirm pagebuilder-components is under htdocs/node_modules/@quatrecentquatre/front-end-tools as in the layout above.