diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index ac13fe16961d4..1d9080985d8e5 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' } @@ -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; @@ -147,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'], }); }, @@ -371,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' } @@ -399,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: @@ -409,16 +410,76 @@ 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.' + } + } + }); + }, + }, + }; +} +``` + +### `suppress` + +

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

+ +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: + +```js title="my-adapter.mjs" ins={13} +export default function createIntegration() { + return { + name: '@example/my-adapter', + hooks: { + 'astro:config:done': ({ setAdapter }) => { + setAdapter({ + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', + supportedAstroFeatures: { + sharpImageService: { + support: 'limited', + 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 + } + } + }); + }, + }, + }; +} +``` + +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() { + return { + name: '@example/my-adapter', + hooks: { + 'astro:config:done': ({ setAdapter }) => { + setAdapter({ + 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: 'all' } } }); @@ -446,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 } @@ -467,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 } @@ -508,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' } @@ -583,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' }