From 3f89f8074b227a8e042bd27f47918529084e997f Mon Sep 17 00:00:00 2001 From: Yan <61414485+yanthomasdev@users.noreply.github.com> Date: Tue, 3 Jun 2025 09:17:09 -0300 Subject: [PATCH 1/6] Document `suppress` in `supportedAstroFeatures` --- .../docs/en/reference/adapter-reference.mdx | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index ac13fe16961d4..ad4f4dd596107 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -71,6 +71,7 @@ export type AdapterSupportsKind = 'unsupported' | 'stable' | 'experimental' | 'd export type AdapterSupportWithMessage = { support: Exclude; message: string; + suppress?: 'default' | 'all'; }; export type AdapterSupport = AdapterSupportsKind | AdapterSupportWithMessage; @@ -428,6 +429,56 @@ export default function createIntegration() { } ``` +If the default log message sent along with your custom message can cause confusion, you can use `suppress: "default"` to suppress the default message: + +```js title="my-adapter.mjs" ins={13} +export default function createIntegration() { + return { + name: '@matthewp/my-adapter', + hooks: { + 'astro:config:done': ({ setAdapter }) => { + setAdapter({ + name: '@matthewp/my-adapter', + serverEntrypoint: '@matthewp/my-adapter/server.js', + supportedAstroFeatures: { + sharpImageService: { + support: 'limited', + message: 'This adapter has limited support for Sharp, certain features may not work as expected.', + suppress: 'default' + } + } + }); + }, + }, + }; +} +``` + +You can also use `suppress: "all"` to suppress all messages for a specific feature, useful if it doesn't impact users in a specific context: + +```js title="my-adapter.mjs" ins={13} +export default function createIntegration() { + return { + name: '@matthewp/my-adapter', + hooks: { + 'astro:config:done': ({ setAdapter }) => { + setAdapter({ + name: '@matthewp/my-adapter', + serverEntrypoint: '@matthewp/my-adapter/server.js', + supportedAstroFeatures: { + sharpImageService: { + support: 'limited', + message: 'This adapter has limited support for Sharp, certain features may not work as expected.', + suppress: 'all' + } + } + }); + }, + }, + }; +} +``` + ## Adapter features A set of features that changes the output of the emitted files. When an adapter opts in to these features, they will get additional information inside specific hooks. From e4cf427b0fb27ece4986e727f21195340241bf7e Mon Sep 17 00:00:00 2001 From: Yan <61414485+yanthomasdev@users.noreply.github.com> Date: Tue, 3 Jun 2025 09:57:14 -0300 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Matt Kane --- src/content/docs/en/reference/adapter-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index ad4f4dd596107..9b1ea00801746 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -71,7 +71,7 @@ export type AdapterSupportsKind = 'unsupported' | 'stable' | 'experimental' | 'd export type AdapterSupportWithMessage = { support: Exclude; message: string; - suppress?: 'default' | 'all'; + suppress?: 'default' | 'all'; }; export type AdapterSupport = AdapterSupportsKind | AdapterSupportWithMessage; From 20179bc8964c1c5f9d186f9c910df1532c331e06 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Tue, 3 Jun 2025 13:06:19 -0300 Subject: [PATCH 3/6] Update adapter-reference.mdx --- .../docs/en/reference/adapter-reference.mdx | 90 ++++++++++--------- 1 file changed, 50 insertions(+), 40 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 9b1ea00801746..ab99e1c51183f 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -26,12 +26,12 @@ An adapter __must__ call the `setAdapter` API in the `astro:config:done` hook li ```js title="my-adapter.mjs" export default function createIntegration() { return { - name: '@matthewp/my-adapter', + name: '@example/my-adapter', hooks: { 'astro:config:done': ({ setAdapter }) => { setAdapter({ - name: '@matthewp/my-adapter', - serverEntrypoint: '@matthewp/my-adapter/server.js', + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', supportedAstroFeatures: { staticOutput: 'stable' } @@ -148,12 +148,12 @@ And then in your integration, where you call `setAdapter`, provide this name in ```js title="my-adapter.mjs" ins={9} export default function createIntegration() { return { - name: '@matthewp/my-adapter', + name: '@example/my-adapter', hooks: { 'astro:config:done': ({ setAdapter }) => { setAdapter({ - name: '@matthewp/my-adapter', - serverEntrypoint: '@matthewp/my-adapter/server.js', + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', exports: ['handler'], }); }, @@ -372,21 +372,21 @@ Astro features are a way for an adapter to tell Astro whether they are able to s When using these properties, Astro will: - run specific validation; -- emit contextual to the logs; +- emit contextual information to the logs; -These operations are run based on the features supported or not supported, their level of support, and the configuration that the user uses. +These operations are run based on the features supported or not supported, their level of support, the [desired amount of logging](#suppress), and the user's own configuration. The following configuration tells Astro that this adapter has experimental support for the Sharp-powered built-in image service: ```js title="my-adapter.mjs" ins={9-11} export default function createIntegration() { return { - name: '@matthewp/my-adapter', + name: '@example/my-adapter', hooks: { 'astro:config:done': ({ setAdapter }) => { setAdapter({ - name: '@matthewp/my-adapter', - serverEntrypoint: '@matthewp/my-adapter/server.js', + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', supportedAstroFeatures: { sharpImageService: 'experimental' } @@ -400,9 +400,9 @@ export default function createIntegration() { If the Sharp image service is used, Astro will log a warning and error to the terminal based on your adapter's support: ``` -[@matthewp/my-adapter] The feature is experimental and subject to issues or changes. +[@example/my-adapter] The feature is experimental and subject to issues or changes. -[@matthewp/my-adapter] The currently selected adapter `@matthewp/my-adapter` is not compatible with the service "Sharp". Your project will NOT be able to build. +[@example/my-adapter] The currently selected adapter `@example/my-adapter` is not compatible with the service "Sharp". Your project will NOT be able to build. ``` A message can additionally be provided to give more context to the user: @@ -410,16 +410,16 @@ A message can additionally be provided to give more context to the user: ```js title="my-adapter.mjs" ins={9-14} export default function createIntegration() { return { - name: '@matthewp/my-adapter', + name: '@example/my-adapter', hooks: { 'astro:config:done': ({ setAdapter }) => { setAdapter({ - name: '@matthewp/my-adapter', - serverEntrypoint: '@matthewp/my-adapter/server.js', + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', supportedAstroFeatures: { sharpImageService: { support: 'limited', - message: 'This adapter has limited support for Sharp, certain features may not work as expected.' + message: 'This adapter has limited support for Sharp. Certain features may not work as expected.' } } }); @@ -429,22 +429,32 @@ export default function createIntegration() { } ``` -If the default log message sent along with your custom message can cause confusion, you can use `suppress: "default"` to suppress the default message: +### `suppress` + +

+ + **Type:** `default | all`
+ +

+ +An option to prevent showing some or all logged messages. + +If Astro's default log message is redundant, or confusing to the user in combination with your custom `message`, you can use `suppress: "default"` to suppress the default message and only log your message: ```js title="my-adapter.mjs" ins={13} export default function createIntegration() { return { - name: '@matthewp/my-adapter', + name: '@example/my-adapter', hooks: { 'astro:config:done': ({ setAdapter }) => { setAdapter({ - name: '@matthewp/my-adapter', - serverEntrypoint: '@matthewp/my-adapter/server.js', + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', supportedAstroFeatures: { sharpImageService: { support: 'limited', - message: 'This adapter has limited support for Sharp, certain features may not work as expected.', - suppress: 'default' + message: 'message: 'The adapter has limited support for Sharp. It will be used for images during build time, but will not work at runtime.', + suppress: 'default' // custom message is more detailed than the default } } }); @@ -454,21 +464,21 @@ export default function createIntegration() { } ``` -You can also use `suppress: "all"` to suppress all messages for a specific feature, useful if it doesn't impact users in a specific context: +You can also use `suppress: "all"` to suppress all messages for a specific feature. This is useful when these messages are unhelpful to users in a specific context. For example, you can choose to prevent logging any messages about Sharp: ```js title="my-adapter.mjs" ins={13} export default function createIntegration() { return { - name: '@matthewp/my-adapter', + name: '@example/my-adapter', hooks: { 'astro:config:done': ({ setAdapter }) => { setAdapter({ - name: '@matthewp/my-adapter', - serverEntrypoint: '@matthewp/my-adapter/server.js', + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', supportedAstroFeatures: { sharpImageService: { support: 'limited', - message: 'This adapter has limited support for Sharp, certain features may not work as expected.', + message: 'This adapter has limited support for Sharp. Certain features may not work as expected.', suppress: 'all' } } @@ -497,12 +507,12 @@ When enabled, this prevents middleware code from being bundled and imported by a ```js title="my-adapter.mjs" ins={9-11} export default function createIntegration() { return { - name: '@matthewp/my-adapter', + name: '@example/my-adapter', hooks: { 'astro:config:done': ({ setAdapter }) => { setAdapter({ - name: '@matthewp/my-adapter', - serverEntrypoint: '@matthewp/my-adapter/server.js', + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', adapterFeatures: { edgeMiddleware: true } @@ -518,12 +528,12 @@ Then, consume the hook [`astro:build:ssr`](/en/reference/integrations-reference/ ```js title="my-adapter.mjs" ins={15-20} export default function createIntegration() { return { - name: '@matthewp/my-adapter', + name: '@example/my-adapter', hooks: { 'astro:config:done': ({ setAdapter }) => { setAdapter({ - name: '@matthewp/my-adapter', - serverEntrypoint: '@matthewp/my-adapter/server.js', + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', adapterFeatures: { edgeMiddleware: true } @@ -559,12 +569,12 @@ Enable the feature by passing any valid `AdapterSupportsKind` value to the adapt ```js title="my-adapter.mjs" ins={9-11} export default function createIntegration() { return { - name: '@matthewp/my-adapter', + name: '@example/my-adapter', hooks: { 'astro:config:done': ({ setAdapter }) => { setAdapter({ - name: '@matthewp/my-adapter', - serverEntrypoint: '@matthewp/my-adapter/server.js', + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', adapterFeatures: { envGetSecret: 'stable' } @@ -634,12 +644,12 @@ This property allows you to force a specific output shape for the build. This ca ```js title="my-adapter.mjs" ins={9-11} export default function createIntegration() { return { - name: '@matthewp/my-adapter', + name: '@example/my-adapter', hooks: { 'astro:config:done': ({ setAdapter }) => { setAdapter({ - name: '@matthewp/my-adapter', - serverEntrypoint: '@matthewp/my-adapter/server.js', + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', adapterFeatures: { buildOutput: 'static' } From a76346c2796c3ecc68c163de596d670e41b68a6d Mon Sep 17 00:00:00 2001 From: Yan <61414485+yanthomasdev@users.noreply.github.com> Date: Tue, 3 Jun 2025 13:15:01 -0300 Subject: [PATCH 4/6] Fix message --- src/content/docs/en/reference/adapter-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index ab99e1c51183f..9ea6de9474792 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -453,7 +453,7 @@ export default function createIntegration() { supportedAstroFeatures: { sharpImageService: { support: 'limited', - message: 'message: 'The adapter has limited support for Sharp. It will be used for images during build time, but will not work at runtime.', + message: 'The adapter has limited support for Sharp. It will be used for images during build time, but will not work at runtime.', suppress: 'default' // custom message is more detailed than the default } } From f7436a84ba3e0b2099d69415cdf169553a9b4841 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Tue, 3 Jun 2025 13:40:04 -0300 Subject: [PATCH 5/6] more explicit about suppressing messages about support for a feature, and an example of when --- src/content/docs/en/reference/adapter-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 9ea6de9474792..308bdb62a8e79 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -464,7 +464,7 @@ export default function createIntegration() { } ``` -You can also use `suppress: "all"` to suppress all messages for a specific feature. This is useful when these messages are unhelpful to users in a specific context. For example, you can choose to prevent logging any messages about Sharp: +You can also use `suppress: "all"` to suppress all messages about support for the feature. This is useful when these messages are unhelpful to users in a specific context, such as when they have a configuration setting that means they are not using that feature. For example, you can choose to prevent logging any messages about Sharp support from your adapter: ```js title="my-adapter.mjs" ins={13} export default function createIntegration() { From 9bdb63fe971894afb65ec477531f4d15ae75e931 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Tue, 3 Jun 2025 14:09:44 -0300 Subject: [PATCH 6/6] make definition clear messages are about supporting the feature, not "all messages" --- src/content/docs/en/reference/adapter-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 308bdb62a8e79..1d9080985d8e5 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -437,7 +437,7 @@ export default function createIntegration() {

-An option to prevent showing some or all logged messages. +An option to prevent showing some or all logged messages about an adapter's support for a feature. If Astro's default log message is redundant, or confusing to the user in combination with your custom `message`, you can use `suppress: "default"` to suppress the default message and only log your message: