Proposal: explicit named imports for non-JS/CSS assets

[gaearon]

Problem

We currently allow you to do this:

import logo from './logo.png';

After getting used to it, you’ll probably be comfortable with this giving you a URL.

But what about other types? For example, what should this return?

import doc from './doc.md';

Markdown source? Compiled HTML? An AST?

What about this?

import Icon from './icon.svg';

Should this give you a link? The SVG content? A React component?

The usual answer is “decide it for yourself in the configuration file”. However, that doesn’t work for CRA so we decided to treat all unknown extensions as URL imports. This is not ideal because in some cases it just doesn’t make any sense, and in others there are advanced (but still relatively common) use cases that aren’t satisfied.

Proposal

What if we allowed to user to pick what they want, from a limited supported subset per filetype?

import { url as logoUrl } from './logo.png';
import { html as docHtml } from './doc.md';
import { ReactComponent as Icon } from './icon.svg';

Named imports are checked by webpack so you’d get a compile error if you use an unsupported one.

Things that are unused will be tree shaken so if you only use e.g. HTML of Markdown files, their source won’t be bundled. Same for SVGs (whether you consume them as raw source, URLs, or React components).

Other zero-configuration tools can also adopt this approach.

Concerns

• What do we do with the default import? Ideally I’d like to forbid it for anything other than JS/CSS because the intent is not clear for asset files (which version do you get?) We could do this with a lint rule.
• If we make the breaking change, how do we update the consumers? We could write a codemod (it should be very simple).
• It would be nice to coordinate this across at least a few other projects (e.g. @ndelangen Storybook). Maybe @KyleAMathews (Gatsby) @devongovett (Parcel) @rauchg (Next) would also be interested? I imagine we’ll need to write a multi-file Webpack loader for this, but I don’t see why other bundlers couldn’t adopt a similar convention.
• Build performance: generating all possible content variations can be too slow. Ideally it would be nice if loaders had information about which import was used.

Thoughts?

[gregberge]

I think it is a very good thing to adopt a convention on it.

Even without talking about zero-configuration, today we can't use several Webpack loaders safely. We had the problem with svgr + url-loader. I made a workaround to solve it but it should not be a workaround.

I think we should add @sokra in this discussion, Webpack could force it by design.

[dmitriid]

What do we do with the default import? Ideally I’d like to forbid it for anything other than JS/CSS because the intent is not clear for asset files (which version do you get?)

We may want to define the rules for the default as and extension of "pick what they want, from a limited supported subset per filetype".

import { url } from './logo.png'

import Logo from './logo.png'

Logo.url === url

Will this work in practice though?

[gaearon]

I think we should add @sokra in this discussion, Webpack could force it by design.

I think this needs to be a grassroots effort because enforcing anything like this from webpack’s side is going to take a super long time, even if they do it.

[gaearon]

@dmitriid

My thinking is that your example shouldn't build because it has a default import (import Icon). I think that if we adopt this approach we should just forbid default import and ask people to be explicit about what they want.

We could maybe keep default import for compatibility reasons for a while.

[Munter]

If you want to foster a culture of zero config tooling, then it would be nice to come up with a convention that doesn't break module imports by default. Using the import statement for anything non-module is already forcing a specific tool chain dependency and thus a default config requirement on the developer.

I'd really love to see a syntax that was actually JS compatible by not overloading the import statement

[gaearon]

@Munter I understand this sentiment but it’s not very practical in my experience. We’re trying to do the best with what we got. FWIW, my proposal is actually closer to no lock-in than syntax like raw!./file.md because at least it is possible to auto-generate file.md.js that contains those exports. So in practice it can even work on Node if you have a codegen step.

Let’s not derail this thread with a general discussion whether import for assets is a good idea. The fact is that it solves many real use cases, and people want to do it. So the question here is how to make that more ergonomic and less confusing.

[gaearon]

I think in order to adopt this we’ll have to keep supporting default import for a while. This will make it possible for tools like Storybook to catch up. Then we can decide whether we want to deprecate support for the default import or not.

[dmitriid]

@gaearon

I think I agree with you in principle, but I think there are potential downsides. Though as I'm writing them down, I feel like I might be wrong about some of my assumptions.

• import * as Icon from 'icon.svg'

In the absence of a default export devs will still attempt the above, which will lead to multiple questions similar to "Why import * as React from 'react' and not import React from 'react'".

Why would dev need * from an svg? Because sometimes they just do :)

• assumption that a default export is just an object with exposed/exported properties

Even though this assumption is incorrect due to how import/loading works, many devs (including me :) ) will assume the following code to be equivalent:

import {prop} from 'something';

// many will assume it to be equivalent to

import Obj from 'something';
const prop = Obj.prop

It doesn't help that a lot of transpiled code looks that way.

[ndelangen]

My first proposal would be to create a multi-markdown-loader that would export all the formats we want. and it could even have a default export. What this default would be exactly, I don't know.

I also see potential for this idea to take hold for other files then markdown.

import { url } from './my.svg';
import { raw } from './my.txt';

[gaearon]

Note there’s also a build performance concern: https://mobile.twitter.com/wSokra/status/950713344163446785.

[ranyitz]

@gaearon, That sounds like an awesome idea!

Supporting the default imports would only be less performant (from bundle size, and compile time aspects) and as you said, a lint rule could do the job for the depreciation period.

About the build performance problem, the loader will process all the possibilities, usually with no need, That might increase the build time.
Ideally, we would like the loader to be triggered by a combination of the extension and the named export, for example:

svg + url => use url-loader

import { url } from './logo.svg';

svg + ReactComponent => use react-svg-loader

import { ReactComponent } from './logo.svg';

I understand that there is a problem to do it in webpack because we only get what the user imported after the loaders ran.

When using static import it should be possible to get that information at an earlier stage.

@sokra, is there a plan of doing something like this?

[gaearon]

Unfortunately @sokra says it’s not easy due to the current architecture: https://mobile.twitter.com/wSokra/status/950728052442529793

[viankakrisna]

maybe it can be implemented as a babel-plugin?

import { raw } from './file.md';

becomes

import raw from 'raw!./file.md';

I think i've seen similar approach (rewriting imports) with babel-plugin-lodash. Can it be applied to loaders too?

[Andarist]

@viankakrisna it could, from the babel's perspective this is just a js syntac and it could transpile it to the custom loader format (import raw from 'raw!./file.md';)

[devongovett]

Yep, Parcel has had requests to get the URL for officially supported formats like JSON instead of inlining into the JS bundle.

The proposed syntax is potentially a bit problematic I think. Should it work for JS imports as well? i.e. import {url} from './my-script.js'. There would be no way to know statically whether url refers to a legit JS export or the URL to the file produced by the bundler, since the file extension is optional to imports.

In Parcel, and I think in webpack too, resolution of dependencies happens later - after loaders have already run. So in order to implement this syntax the loader would need to do its own resolution to check if it's a JS file. Also, I don't think we should treat JS files specially - you should be able to import a URL to a JS file as well.

[gregberge]

@devongovett the problem is already present with JS files. If I apply url-loader on JS files, I can't access the JS code itself any more.

But thinking about the JS file case, I don't know how to solve this issue. It seems more complicated than it appears.

[FWeinb]

@viankakrisna
Can be done with a babel-plugin, quick test here.

[sompylasar]

import { [Symbol.url] as jsUrl } from './foo.js'; — can this work? Getting a JS URL is a rare case if we have dynamic import().

RE: loaders do their own resolving, if resolving is exposed as a function (memoized somehow?), it can be reused from a loader.

[yyx990803]

For the record, I'm interested in implementing this is the new vue-cli default configuration.

I was about to propose doing this via a babel-plugin but someone beat me to it :)

I think babel plugin is a good idea:

• applicable to any file type, no need to implement a mega-loader or different loaders for different file types.
• no tree-shaking needed
• no perf concerns

What @FWeinb showed is already promising.

Note: the babel plugin is webpack-specific, implementation for Parcel probably has to be done in a completely different fashion.

[bmeck]

Is there any problems with doing this via a URL Query Parameter so that it could also function in other places?

[stereobooster]

Also want to let you know about another potential use case (from svelte)

import MyComponent from './MyComponent.html';

[sompylasar]

Is there any problems with doing this via a URL Query Parameter so that it could also function in other places?

If by URL Query Parameter you mean something like import foo from './foo.svg?ReactComponent' (altering the module request syntax) then it's as not standardized and webpack-specific as import foo from 'react-svg-loader!./foo.svg'.

Having a set of named exports from modules is not standardized as well, but may be easier to standardize across bundlers, also may be easier to provide type definitions.

[bmeck]

@sompylasar Query Parameters are supported by browsers and servers, I'm not sure how this specific name list style of solution could be supported in those environments.

[dmwyatt]

Anyone still thinking about or working on this?

Is there currently a workaround with CRA to get file contents as a string?

edit: Meaning, other than using the !raw-loader! syntax.

[xAlien95]

Is there currently a workaround with CRA to get file contents as a string?

@dmwyatt, you can use a babel-plugin-macro such as raw.macro.

import raw from 'raw.macro';

const markdown = raw('./README.md');

File contents will be bundled within main.[hash].chunk.js.

[pReya]

@xAlien95 This would still require ejecting in CRA, right? It'd be great to find a way without ejecting.

[xAlien95]

@xAlien95 This would still require ejecting in CRA, right? It'd be great to find a way without ejecting.

@pReya, no, macros are there to not eject. The only thing a macro can't do is to handle react-hot-loading, so if you make an edit in a Markdown file imported with raw.macro you'll need to restart the developer server to see the changes.

[dmwyatt]

I think if I'm not going to be able to use a "regular" import, I'd rather npm install raw-loader and then import readme from '!raw-loader!./README.md'.

[devuxer]

@gaearon, Is this still under consideration?

[transitive-bullshit]

I think going with the solution @xAlien95 proposed and relying on babel-plugin-macros will be better than bloating CRA with more features like this proposal.

The only real actionable thing I'd suggest would be adding this to the official FAQ.

[zaydek]

I just wanted to add that raw.macro is working extremely well for me:

const Core = props => <style>{raw("./core.css")}</style>
const InlineBackground = props => <style>{raw("./inline-background.css")}</style>
const Monospace = props => <style>{raw("./monospace.css")}</style>
const PreviewMode = props => <style>{raw("./preview-mode.css")}</style>
const ProportionalType = props => <style>{raw("./proportional-type.css")}</style>

OP here.

[wapiflapi]

Using raw.macro, how can I add those files to the list of files npm start watches?

import raw from 'raw.macro';

const markdown = raw('./README.md');

When changing the contents of the markdown file I expect a reload. I can't seem to find how to achieve this without ejecting.

Ideally it would watch only the "imported" files, but if I could set it up so it watches *.md I'd be fine with that too.

If any one can help me out, this might be a useful thing to add to a FAQ (or at least this issue which google digs up.)

[zaydek]

@wapiflapi I also expected hot reloads but this works differently. As far as I’m aware, that would need to be something webpack handles in order for hot-reloading to just work. But this isn’t webpack -- this is a Babel macro; Babel is actually reading and injecting your .md source as a string in your source code using Node.js functionality.

Unless I’m missing something, React apps can’t leverage Node functions like readFileSync, etc. because they’re web apps. The raw.macro import is very clever because it works around the CRA ecosystem, but in doing so also breaks hot-reloading.

You could watch the files for changes but you’d have to hard-start your React app every time, the equivalent of yarn start, which takes a few seconds.

This is at least my understanding of what’s going on. 🤔

[dan-dr]

Doesn't seem to work with dynamic imports

[luigimannoni]

raw.macro is broken and no longer works as per latest create-react-app version, upgrading the whole project to the latest react is a bit painful.
Using import !raw-loader!... doesn't seem to import the entire file as string but spits out the url reference, which I cannot use for .glsl shader files.

I did eventually export the whole files as a huge single ES6 templated string

[rjgotten]

As of Webpack 5 you don't need anything special anymore. The only thing you need is CRA to add a module rule that treats known query string values as monikers to map to either the asset/inline or asset/source asset module type and then you're done:
https://webpack.js.org/guides/asset-modules/#replacing-inline-loader-syntax

At the very least CRA should just define the given example rule for ?raw as an escape hatch, and then leave it up to application developers to further handle that content how they want to. This is compatible with dynamic imports as well, so it handles both inlined source as well as on-demand content. If you need it on-demand; simply use a dynamic import.