Overview

Drupal Canvas provides several utilities, a FormattedText component, and autoconfigured @drupal-api-client/json-api-client and next-image-standalone packages for use in code components. Currently these are not really possible to be used outside of Canvas in a React codebase used with @drupal-canvas/cli to develop Canvas components.

Proposed resolution

Extract those elements to a separate package that can be used both in Canvas and outside it in a React codebase.

  1. Add a new package under packages/drupal-canva which will be publish as drupal-canvas.
  2. The following elements should be moved from ui/lib/astro-hydration/src/lib to the new package and, if needed, adapted to work also outside Canvas:
    • @/lib/drupal-utils
    • @/lib/FormattedText
    • @/lib/jsonapi-utils
    • @/lib/utils
    • @drupal-api-client/json-api-client
      The automatic configuration of the client will need to be adapted to also work outside Canvas in a React codebase. The client should know how to connect to a Drupal site so lists can be built locally. The base URL can be read from the environment variable that would be set up for the CLI tool. The tricky part is exposing the jsonapi.base_path service parameter. See how it was done in a browser context #3536124: Configure Drupal API Client automatically for code components.
    • next-image-standalone
      The image component in context outside Canvas should provide a loader that just returns the same image URL/path without any optimization. Trying to optimize example images from component.yml files might need #3559717: Image SDC does not generate srcset attribute for example images to work first, though that is for SDCs, but maybe it’s a similar challenge under the hood.

    The package should provide named exports from the main file to allow for import autocompletion and provide a single package to import from (e.g. import { Image, JsonApiClient } from 'drupal-canvas') but also still provide separate exports compatible with the current ones to allow for maintaining backward-compatible import map entries (e.g. import Image from 'next-image-standalone' or import { JsonApiClient } from '@drupal-api-client/json-api-client'; that can be mapped using the import map to import Image from 'drupal-canvas/next-image-standalone' or import { JsonApiClient } from 'drupal-canvas/json-api-client').

  3. Add the new package as a dependency of @drupal-canvas/ui and update the import map (1, 2) to point existing entries to the new package and add a new entry for the package itself.
  4. Update user documentation on packages, data fetching, and responsive images to include information about the new package and use it in code examples.
  5. Update component-imports rule in the @drupal-canvas/eslint-config to:
    • allow imports from the new package,
    • and to warn about existing import specifiers being deprecated in favor of the new package.

Issue fork canvas-3560419

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

wotnak created an issue. See original summary.

wotnak’s picture

wotnak
he/him
commented
Assigned: Unassigned » wotnak

wotnak opened merge request !383

wotnak’s picture

wotnak
he/him
commented
Assigned: wotnak » balintbrews
Status: Active » Needs review

Most moved utils worked as is. The image loader already had a fallback to the original URL.
When it comes to JsonApiClient, getting autoconfiguration working outside Drupal Canvas in a local React codebase wasn't really possible without changes to specific dev env. To allow developing components using JSONAPI in a local dev env I settled on creating a Vite plugin that, based on env variables (CLI's CANVAS_SITE_URL and additional optional CANVAS_JSONAPI_PREFIX), injects drupalSettings.canvasData variables that JsonApiClient uses for autoconfiguration. The plugin also configures resolving of the @/components/ alias based on CLI's CANVAS_COMPONENT_DIR env variable.

@drupal-canvas/eslint-config component-imports rule was updated to also, when possible, provide automatic fixes for imports of elements moved into the drupal-canvas package.

drupal-canvas package is now a dependency of ui/lib/astro-hydration, so npm workspaces configuration had to be changed. astro-hydration was added to the root workspace and removed from the ui workspace.
If in the future we will want to add ui to the root workspace, it will be a more complicated process. NPM cli has problems with installing dependencies of workspace packages when they are nested inside each other (like astro-hydration is inside ui) and the UI build job in GitLab CI saves node_modules as an artifact, but the root node_modules dir with ui dependencies included is currently too big, and GitLab hits the size limit when trying to save it as a job artifact.

Since tsup (used for building other packages included in the repo) is no longer actively maintained (https://github.com/egoist/tsup#readme), I used tsdown for building the new packages.

balintbrews made their first commit to this issue’s fork.

balintbrews’s picture

balintbrews
he/him/his
Primary language Hungarian
Location Netherlands 🇪🇺
commented
Assigned: balintbrews » Unassigned
Status: Needs review » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

wotnak opened merge request !427

  • wotnak committed 3b186788 on 1.x 
    chore: #3560419 update eslint-config version used in CLI to include...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.