feat: add Vite plugin to Netlify adapter by eduardoboucas · Pull Request #13768 · withastro/astro

eduardoboucas · 2025-05-08T09:44:22Z

Changes

Loads the new (and experimental) Netlify Vite plugin, which means a few things:

The environment is populated with the Netlify global, as well as the globals needed to use Netlify Blobs and the upcoming Netlify Cache API straight from astro dev, without requiring the Netlify CLI
Starting up astro dev will make the plugin automatically add the .netlify directory to the .gitignore file, like the Netlify CLI does
The plugin will suggest that the user links the project is linked to a Netlify site, if it isn't already linked

I'm keeping it as draft for now because I still need to add some tests and update docs (see below). And above all, I'd love to hear your feedback, since this is a net new flow we're introducing.

Testing

I'd like to add some tests, but from a quick look it seems that the existing tests only assert the build output. Do we have a way to test the development flow?

Docs

I think we should update docs for this, both on the Astro side and on the Netlify side, explaining what will now become available during the local development process.

/cc @withastro/maintainers-docs for feedback!

changeset-bot · 2025-05-08T09:44:26Z

🦋 Changeset detected

Latest commit: 147b2ab

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

ascorbic · 2025-05-08T11:27:45Z

Cool! What happens if a user runs it via the Netlify CLI? Will it end up running both? Maybe it should be conditionally loaded in that case

eduardoboucas · 2025-05-08T13:11:54Z

Cool! What happens if a user runs it via the Netlify CLI? Will it end up running both? Maybe it should be conditionally loaded in that case

Good point! We should be able to use environment variables to detect whether we're running inside the Netlify CLI and make it a no-op in that case. I just need to think of the best place to check that.

eduardoboucas · 2025-05-09T09:42:02Z

Updated in 0630323 via netlify/primitives#181.

ascorbic · 2025-05-09T11:06:53Z

Take a look at this for an example of running dev mode tests:

https://github.com/withastro/astro/blob/main/packages/astro/test/sessions.test.js#L135

ascorbic · 2025-06-04T06:08:39Z

@eduardoboucas now the plugin is no longer experimental, do you want to finish off the PR and get this merged?

eduardoboucas · 2025-06-17T16:51:31Z

@eduardoboucas now the plugin is no longer experimental, do you want to finish off the PR and get this merged?

Yes! I've just updated the version of the plugin and added some tests.

I'm sure there's lots more we can do to make the integration even nicer, but I think this would be a good first step. Let me know your thoughts!

serhalp

LGTM 🚀

serhalp · 2025-06-17T18:21:55Z

packages/integrations/netlify/test/development/fixtures/primitives/astro.config.mjs

+  adapter: netlify({
+    edgeMiddleware: process.env.EDGE_MIDDLEWARE === 'true',
+    imageCDN: process.env.DISABLE_IMAGE_CDN ? false : undefined,
+  }),


nit: AFAICT from spelunking these are unused here

Suggested change

adapter: netlify({

edgeMiddleware: process.env.EDGE_MIDDLEWARE === 'true',

imageCDN: process.env.DISABLE_IMAGE_CDN ? false : undefined,

}),

adapter: netlify(),

ascorbic · 2025-06-18T05:23:29Z

packages/astro/test/fixtures/primitives/.gitignore

@@ -0,0 +1,2 @@
+# Local Netlify folder


I think this is in the wrong place

Removed in 087d488.

packages/integrations/netlify/test/development/primitives.test.js

ascorbic

Thanks! There are a few places in the adapter code where we check if we're running in the Netlify CLI before enabling/disabling various options. e.g. when it's not running in the Netlify CLI, we don't use the image CDN or blobs. These checks should be removed so we can use the primitives in dev.

packages/integrations/netlify/test/development/fixtures/primitives/package.json

ascorbic · 2025-06-18T06:04:24Z

The tests are timing-out because they're never exiting. I'm not sure why, because it is stopping the dev server. Did this happen for you when you ran them locally?

ascorbic

It looks like something isn't being cleaned-up, meaning Node never exits. Presumably one of the Netlify servers? Is there a way we can ensure that they all shut down when the parent dev server exits?

ematipico · 2025-06-18T12:48:45Z

The tests are timing-out because they're never exiting. I'm not sure why, because it is stopping the dev server. Did this happen for you when you ran them locally?

It's possible that this branch was created from an outdated main branch.

eduardoboucas · 2025-06-18T12:49:47Z

The hanging tests were caused by an issue on our side, which I have fixed in netlify/primitives#310.

I'm expecting them to pass now. ⏳

ematipico

Thank you @eduardoboucas, for the PR. Fortuantely the code changes are minimal, which they seem good. However, I have some concerns regarding docs and expectations. Could you clarify them?

ematipico · 2025-06-18T12:49:55Z

packages/integrations/netlify/src/index.ts

 					},
 					session,
 					vite: {
+						plugins: [netlifyVitePlugin()],


Shouldn't we add this plugin only when running the dev command? That's what I understood from the PR description

It looks like the plugin only implements the configureServer hook, so it won't affect builds: https://github.com/netlify/primitives/blob/main/packages/vite-plugin/src/main.ts

I'm happy to make this more explicit on the adapter side if needed. What's your recommendation?

I think just a mention in the docs of the plugin is more than enough :)

ematipico · 2025-06-18T12:54:58Z

...es/integrations/netlify/test/development/fixtures/primitives/netlify/edge-functions/yell.mjs

I suppose this file and netlify/functions/func.mjs are part of the Netlify Vite plugin; however, the plugin's documentation doesn't mention these files.

I would appreciate if you could update the PR description, and guide us reviewers to understand what these files are for, and what we should expect.

Additionally, is there a link we can use to redirect our users to instructions on how to use these files?

Those are just regular Netlify functions and edge functions, rather than anything related to the Vite plugin specifically. There's some info here: https://docs.astro.build/en/guides/deploy/netlify/#using-netlify-functions

What should we expect from these functions though?

I think just that they work as expected on a Netlify site (i.e. they run when they match a route)

eduardoboucas · 2025-06-18T13:08:36Z

Thanks! There are a few places in the adapter code where we check if we're running in the Netlify CLI before enabling/disabling various options. e.g. when it's not running in the Netlify CLI, we don't use the image CDN or blobs. These checks should be removed so we can use the primitives in dev.

@ascorbic Mind if we do this as a follow-up? I'd love to get the skeleton landed first.

chee · 2025-06-30T20:45:39Z

yay

ascorbic · 2025-07-01T08:59:32Z

It looks like this is ready! Can you do a changeset? We should be able to get this in 5.11, and it would be great to be able to highlight this in the blog. The changeset should be written for the audience of end users, so rather than explaining the technical implementation in any detail (beyond saying that it now uses the Netlify Vite plugin), focus on what this means for the user.

Are there any changes needed for docs? Does it change any of the instructions in the deployment guide or adapter docs?

ascorbic · 2025-07-01T11:57:48Z

packages/integrations/netlify/src/index.ts

 					image: {
 						service: {
-							entrypoint: enableImageCDN ? '@astrojs/netlify/image-service.js' : undefined,
+							entrypoint: integrationConfig?.imageCDN ? '@astrojs/netlify/image-service.js' : undefined,


This should default to true, so something like this (with a comment explaining why):

Suggested change

entrypoint: integrationConfig?.imageCDN ? '@astrojs/netlify/image-service.js' : undefined,

entrypoint: integrationConfig?.imageCDN === false ? undefined : '@astrojs/netlify/image-service.js',

.changeset/four-eels-occur.md

sarah11918

This sounds fantastic! 🙌

Left some thoughts for the changeset for your consideration!

.changeset/four-eels-occur.md

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

* feat: load Netlify Vite plugin * chore: update `@netlify/vite-plugin` * update plugin and add tests * Update pnpm-lock.yaml * remove unused code * Deps * update plugin * remove unused file * Apply suggestions from code review Co-authored-by: Matt Kane <m@mk.gg> * Upgrade vite plugin * satisfy linter * Upgrade vite plugin * refactor: use Netlify primitives * make imageCDN an opt out, not an opt in * remove outside netlify test, for now we are never outside * update pnpm-lock * invalidate the astro session when restarting dev server * Update to latest vite plugin, functions and blobs * Add changeset for @astrojs/netlify on @netlify/vite-plugin * apply Sarah's changeset improvements Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --------- Co-authored-by: Matt Kane <m@mk.gg> Co-authored-by: chee <chee.rabbits@netlify.com> Co-authored-by: chee <chee@rabbits.computer> Co-authored-by: chee <yay@chee.party> Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

feat: load Netlify Vite plugin

d0c60aa

github-actions bot added the pkg: integration Related to any renderer integration (scope) label May 8, 2025

chore: update @netlify/vite-plugin

0630323

eduardoboucas added 4 commits June 17, 2025 17:34

update plugin and add tests

d6dcb95

Merge branch 'main' into eb/netlify-vite-plugin

2e69f06

Update pnpm-lock.yaml

1fcfcee

remove unused code

ba0e020

eduardoboucas marked this pull request as ready for review June 17, 2025 16:49

serhalp reviewed Jun 17, 2025

View reviewed changes

ascorbic reviewed Jun 18, 2025

View reviewed changes

packages/integrations/netlify/test/development/primitives.test.js Outdated Show resolved Hide resolved

ascorbic reviewed Jun 18, 2025

View reviewed changes

packages/integrations/netlify/test/development/fixtures/primitives/package.json Show resolved Hide resolved

ascorbic reviewed Jun 18, 2025

View reviewed changes

Deps

fcebe67

eduardoboucas mentioned this pull request Jun 18, 2025

fix: clean up edge functions server netlify/primitives#310

Merged

update plugin

ae1d418

ematipico reviewed Jun 18, 2025

View reviewed changes

remove unused file

087d488

chee force-pushed the eb/netlify-vite-plugin branch from e192940 to 2825dc3 Compare June 30, 2025 17:41

chee added 2 commits June 30, 2025 18:42

Upgrade vite plugin

699a4da

Merge remote-tracking branch 'origin/main' into eb/netlify-vite-plugin

dd479d7

chee force-pushed the eb/netlify-vite-plugin branch from 2825dc3 to dd479d7 Compare June 30, 2025 17:43

chee added 3 commits June 30, 2025 18:44

Merge remote-tracking branch 'upstream/main' into eb/netlify-vite-plugin

4b2797b

satisfy linter

043f953

Upgrade vite plugin

45b9b21

refactor: use Netlify primitives

9b26f3e

ascorbic reviewed Jul 1, 2025

View reviewed changes

chee and others added 3 commits July 1, 2025 13:19

make imageCDN an opt out, not an opt in

011a7ba

remove outside netlify test, for now we are never outside

e72b9e2

Merge branch 'main' into eb/netlify-vite-plugin

d7e90d2

chee mentioned this pull request Jul 7, 2025

fix: apply fixes required for Vite plugin in Astro netlify/primitives#332

Merged

update pnpm-lock

364ac21

chee force-pushed the eb/netlify-vite-plugin branch from d584b7c to 364ac21 Compare July 7, 2025 16:50

chee and others added 2 commits July 7, 2025 18:08

invalidate the astro session when restarting dev server

5a4a7ee

Update to latest vite plugin, functions and blobs

e42e6cc

chee force-pushed the eb/netlify-vite-plugin branch from 85679b9 to 2f0cfd8 Compare July 9, 2025 07:15

Add changeset for @astrojs/netlify on @netlify/vite-plugin

b835391

chee force-pushed the eb/netlify-vite-plugin branch from 2f0cfd8 to b835391 Compare July 10, 2025 09:04

ascorbic reviewed Jul 10, 2025

View reviewed changes

.changeset/four-eels-occur.md Outdated Show resolved Hide resolved

sarah11918 reviewed Jul 10, 2025

View reviewed changes

.changeset/four-eels-occur.md Outdated Show resolved Hide resolved

apply Sarah's changeset improvements

147b2ab

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

ascorbic merged commit faa0eff into withastro:main Jul 10, 2025
15 checks passed

astrobot-houston mentioned this pull request Jul 10, 2025

[ci] release #14047

Merged

chee deleted the eb/netlify-vite-plugin branch July 10, 2025 18:45

ascorbic added this to the v5.12.0 milestone Jul 14, 2025

	entrypoint: integrationConfig?.imageCDN ? '@astrojs/netlify/image-service.js' : undefined,
	entrypoint: integrationConfig?.imageCDN === false ? undefined : '@astrojs/netlify/image-service.js',

Uh oh!

Conversation

eduardoboucas commented May 8, 2025

Changes

Testing

Docs

Uh oh!

changeset-bot bot commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

ascorbic commented May 8, 2025

Uh oh!

eduardoboucas commented May 8, 2025

Uh oh!

eduardoboucas commented May 9, 2025

Uh oh!

ascorbic commented May 9, 2025

Uh oh!

ascorbic commented Jun 4, 2025

Uh oh!

eduardoboucas commented Jun 17, 2025

Uh oh!

serhalp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ascorbic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ascorbic commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ascorbic left a comment

Choose a reason for hiding this comment

Uh oh!

ematipico commented Jun 18, 2025

Uh oh!

eduardoboucas commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ematipico left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eduardoboucas commented Jun 18, 2025

Uh oh!

chee commented Jun 30, 2025

Uh oh!

ascorbic commented Jul 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sarah11918 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

changeset-bot bot commented May 8, 2025 •

edited

Loading

ascorbic commented Jun 18, 2025 •

edited

Loading

eduardoboucas commented Jun 18, 2025 •

edited

Loading

sarah11918 left a comment •

edited

Loading