Push to Canvas
Before pushing, confirm the user has Drupal Canvas CLI installed and configured
for their target site.
Setup gate
Before running any push command:
- Check that a file exists in the project root.
- If exists, verify these values are set:
- If is missing, or any required value is missing, stop and ask the
user to complete setup first.
- Do not guess setup steps. Point the user to the official docs:
- Continue only after the user confirms setup is complete.
Run push
When component work is complete and validated, ask the user if they would like
to push the current Canvas changes to Canvas.
will push all
current changes; it does not support selecting specific components. If there are
unrelated or unvalidated Canvas changes in the working tree, stop and ask the
user how they want to proceed. Make sure to use the right package manager. For
example, if using npm, run the following command:
Handling push failures
Default behavior: always retry failed pushes unless the error is clearly a
connection/setup failure.
Retry pushes 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 push 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:
Ask them to verify and update
values (
,
,
) and OAuth/CLI setup, then retry the
push only after they confirm setup updates are complete.
Dependency-related failures
When pushing multiple new components where one component depends on another
(e.g.,
imports
), the push may fail with a message indicating
that a component doesn't exist. This happens when a component that includes
another gets pushed before its dependency.
This is expected behavior. Simply retry the push command. On subsequent
attempts, the dependencies that were successfully pushed in the previous run
will already exist, allowing the dependent components to push successfully.
Example scenario:
- First push attempt: fails because doesn't exist yet, but
pushes successfully.
- Second push attempt: now succeeds because exists.
If pushes continue to fail after multiple retries, check that all required
dependency components are part of the current local changes or already exist in
Canvas.