canvas-component-upload

Upload to Canvas

Before uploading, confirm the user has Drupal Canvas CLI installed and configured for their target site.

Setup gate

Before running any upload command:

1. Check that a .env file exists in the project root.
2. If .env exists, verify these values are set:
   • CANVAS_SITE_URL
   • CANVAS_CLIENT_ID
   • CANVAS_CLIENT_SECRET
3. If .env is missing, or any required value is missing, stop and ask the user to complete setup first.
4. Do not guess setup steps. Point the user to the official docs:
   • Drupal Canvas OAuth module setup: https://git.drupalcode.org/project/canvas/-/tree/1.x/modules/canvas_oauth#2-setup
   • Drupal Canvas CLI package/docs: https://www.npmjs.com/package/@drupal-canvas/cli
5. Continue only after the user confirms setup is complete.

Run upload

When component work is complete and validated, ask the user if they would like to upload the modified components to Canvas. Make sure to use the right package manager. For example, if using npm, run the following command:

npx canvas upload -c component1,component2,component3 -y

Replace component1,component2,component3 with the actual component names that were created or modified (e.g., canvas upload -c button,card,hero).

Handling upload failures

Default behavior: always retry failed uploads unless the error is clearly a connection/setup failure.

Retry uploads when the failure indicates the Canvas app connection is already working (for example, dependency/order-related component errors). Do not retry connection/setup failures.

Connection/setup failures: Stop, do not retry

If upload fails with authentication, authorization, or network/connection errors, stop and ask the user to complete or verify setup first. This includes errors like invalid credentials, unauthorized/forbidden responses, DNS issues, connection refused, host unreachable, request timeout before reaching Canvas, or TLS/SSL handshake/certificate failures.

Point the user to the official setup docs:

• Drupal Canvas OAuth module setup: https://git.drupalcode.org/project/canvas/-/tree/1.x/modules/canvas_oauth#2-setup
• Drupal Canvas CLI package/docs: https://www.npmjs.com/package/@drupal-canvas/cli

Ask them to verify and update .env values (CANVAS_SITE_URL, CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET) and OAuth/CLI setup, then retry the upload only after they confirm setup updates are complete.

Dependency-related failures

When uploading multiple new components where one component depends on another (e.g., hero imports heading), the upload may fail with a message indicating that a component doesn’t exist. This happens when a component that includes another gets uploaded before its dependency.

This is expected behavior. Simply retry the upload command. On subsequent attempts, the dependencies that were successfully uploaded in the previous run will already exist, allowing the dependent components to upload successfully.

Example scenario:

1. First upload attempt: hero fails because heading doesn’t exist yet, but heading uploads successfully.
2. Second upload attempt: hero now succeeds because heading exists.

If uploads continue to fail after multiple retries, check that all dependency components are included in the upload command.