feat: export helpers to allow 3rd parties to emit assets

[timacdonald]

Description

When using Vite as the build tool for server side language templated views, such as Laravel Blade (or PHP, Ruby, etc), it can be useful to inject assets into the build that are not referenced in JS or CSS "entry points".

Imagine the following contrived Blade template in an application that does not include any built JS or CSS:

@php
    $logo = Arr:random([
       'resources/images/logo-a.png',
       'resources/images/logo-b.png',
    ]);
@endphp

<img src="{{ $logo }}">

Vite does not compile or know about this template, so Vite has no way of knowing about the two logos that the developer wants to bundle.

To allow applications that do not include build entry points to also utilise Vite as a build tool, I would like to propose that Vite export the suggested functions. Exporting these functions allows plugins (namely, the official Laravel plugin) to inject assets that are to be included in the build.

As an example of what this unlocks: in the Laravel plugin we could offer a new key for paths to include in the build:

export default defineConfig({
    plugins: [
        laravel({
            assets: [
                "resources/images/**",
                "resources/fonts/**",
            ],
        }),
        viteImagemin(),
    ],
})

The Laravel plugin may then internally use this emitFile function to add these to the build. Having access to these internal function allows us to ensure we stay inline with Vite naming conventions and also handle the naming as per the default or overridden config for filename ([hash], [name], etc) patterns.

{
    /* ... */
    async buildStart() {
        resolveAssetsFromConfig().forEach(asset => {
            const content = await fsp.readFile(
                path.resolve(resolveConfig.root, asset)
            )

            this.emitFile({
                type: 'asset',
                source: content,
                name: asset,
                fileName: assetFileNamesToFileName(
                    resolveAssetFileNames(resolvedConfig),
                    asset,
                    getHash(content),
                    content
                ),
            })
        }),
    },
}

Why not just use the static copy plugin?

As shown in an earlier example, including these in the actual build allows vite plugins such as viteImagemin to "just work". Images included in the Laravel plugin then benefit from the same side-effects as if the assets were simply referenced in JS files.

Why not just import into your JS

Our current solution is that we recommend people still have an app.js and import images with globing:

import.meta.glob(['../images/**', '../fonts/**'])

However we feel this is really weird workaround for apps that literally don't have any JS in their app, thus we would love to be able to improve this experience for our plugin users.

Additional context

• errrmmmm. maybe have a look at the fact that I had to bump the bundle size substantially 🙈
• If you can think of another way to handle this that I haven't seen, please educate me ❤️

---

What is the purpose of this pull request?

• Bug fix
• New Feature
• Documentation update
• Other

Before submitting the PR, please make sure you do the following

• Read the Contributing Guidelines.
• Read the Pull Request Guidelines and follow the Commit Convention.
• Check that there isn't already a PR that solves the problem the same way to avoid creating a duplicate.
• Provide a description in this PR that addresses what the PR is solving, or reference the issue that it solves (e.g. fixes #123).
• (n/a) Ideally, include relevant tests that fail without this PR but pass with it.

[timacdonald]

Linter was complaining about the trailing backslash

[timacdonald]

Linter was complaining about the missing dash

[timacdonald]

hey @ElMassimo, have you come up with an elegant way of handling this in Ruby land that I might have missed?

[ElMassimo]

@timacdonald Vite Ruby provides an additionalEntrypoints option, which by default includes images, fonts, and icons in the sourceCodeDir, and is fully configurable.

vite-plugin-ruby will fingerprint those assets and emit the corresponding files, adding them to a separate manifest-assets.json file which vite_ruby can use to reference them as needed when vite_asset_path is used.

---

A little history:

Until vite@2-beta.51, Vite supported asset entrypoints (accidentally, perhaps). When support was removed, I opened:

• Regression (beta 51) - Manifest entries for SVG assets lack information to resolve the file #1765
• fix: Modify manifest entries for asset entrypoints (close #1765) #1774

but they were closed as wontfix (hence, the approach in vite-plugin-ruby):

the manifest (...) strictly assumes entries are js chunks and assets are just emitted files that belongs to chunks.

That's no longer true, as vite@3 added back support for CSS entrypoints, which will be added to the manifest as well:

• Assets entries in the manifest do not preserve the original file extension #8764
• fix: preserve extension of css assets in the manifest #8768

---

As Vite became more used in backend integrations, the manifest became more important than initially anticipated, so it looks like we are circling back to #1765.

From my point of view, it would be better if Vite processed any file provided in rollupOptions.input and added it to the manifest, which would ensure any fingerprinting and processing goes through the plugin pipeline. Vite would discard the "fake" JS chunks as needed, as it currently happens for CSS assets.

[timacdonald]

Thank you so much for this insight. I agree that a first party solution would be lovely (although I understand we are both a little bias for making things work with Bbck-end projects as well as possible hehe 😇)

From what I can see, you have had to replicate all of the functionality that I'm proposing Vite export. If an end-user was to change the naming convention used in rollup.output.assetFileNames, your plugin would not currently respect it - or you'd have to re-implement it yourself.

So I can see a benefit for Vite ruby in also having the proposed functions exported as well (again, assuming that there isn't a first party solution). Would you agree?

[patak-dev]

I think the backend integrations ecosystem in Vite has changed enough in the past year that there is merit in having a rediscussion, more now that the manifest includes non-js assets (that was one of the reasons Evan wasn't onboard with the idea #1765 (comment)). Exposing all the needed helpers may be more problematic than providing a first-class solution.

@ElMassimo @timacdonald we're going to set up a vitejs/rfcs repo to formalize the RFC process. I think an RFC could be a good way to get the different parties involved and propose this Vite feature.

[ElMassimo]

Exposing all the needed helpers may be more problematic than providing a first-class solution.

Agreed, exposing the helpers in the public API would make any internal change a potential breaking change.

a first party solution would be lovely

Happy to chime in if @timacdonald likes the idea of opening an RFC for this, it would benefit all backend integrations.

[timacdonald]

Hey folks,

If that is how we wanna move forward - I'm more than happy to whip something up. Should I open a PR against https://github.com/vitejs/rfcs and are there any guidelines or anything?

Should I just take a look at the Vue RFC stuff and try to replicate that in the Vite repo?

[patak-dev]

Hey @timacdonald, Anthony has been working today to set up the vitejs/rfcs repo. We are going to use something similar to Vue, although with some simplifications. There are already docs there in the Readme that you can follow. I think what we are missing is some automation to auto-create a discussion after a PR when needed, but you can do it by hand for now.

[antfu]

@timacdonald The RFC repo is ready, and you can follow the instruction on the repo readme. Looking forward to seeing your RFC!

[sapphi-red]

Closing as #10909 removed assetFileNamesToFileName and resolveAssetFileNames and this PR doesn't make sense any more.

@timacdonald When fileName is omitted from this.emitFile, the file name will be resolved by rollup.output.assetFileNames. Maybe you could just omit fileName like this?

{
    /* ... */
    async buildStart() {
        resolveAssetsFromConfig().forEach(asset => {
            const content = await fsp.readFile(
                path.resolve(resolveConfig.root, asset)
            )

            this.emitFile({
                type: 'asset',
                source: content,
                name: asset, // maybe this should be `path.basename(assets)` instead
            })
        }),
    },
}