Skip to content

Instantly share code, notes, and snippets.

@defunctzombie
Last active July 15, 2024 04:13
Show Gist options
  • Save defunctzombie/4339901 to your computer and use it in GitHub Desktop.
Save defunctzombie/4339901 to your computer and use it in GitHub Desktop.
browser field spec for package.json
@thomasfr
Copy link

thomasfr commented Nov 7, 2014

It is not completely related to this, but i want to extend the concept of client side (only) libraries npm. Imo the problem of client side dependencies with js, css, etc. is still not solved yet. There are tools for some parts of it but no common specification or configuration etc. What about other client side assets like css, less or images? At the moment thats completely missing in my opinion.

There is already the directories property in the CommonJS spec, but it is missing keys for static assets like css, less, images, etc. (http://wiki.commonjs.org/wiki/Packages/1.0#Optional_Fields and https://www.npmjs.org/doc/files/package.json.html#directories)

There are tons of great client side libraries on npm but every single one is different to use / consume in the frontend when it comes to css, less, sass, images, fonts, etc. How to include them? What files should be included? In which order? It would be great if package maintainers could clearly describe what additional assets, besides javascript are shipped with the npm package and how to consume them.

Lets take bootstrap as an example (original https://github.com/twbs/bootstrap/blob/master/package.json)
Why not?


{
  "name": "bootstrap",
  "description": "The most popular front-end framework for developing responsive, mobile first projects on the web.",
  "version": "3.3.0",
  "homepage": "http://getbootstrap.com",
  "author": "Twitter, Inc.",
  "scripts": {
    "test": "grunt test"
  },
  "directories": {
    "assets": {
       "css": ["dist/css/bootstrap.min.css","dist/css/bootstrap-theme.min.css"],
       "js":["dist/js/bootstrap.min.js"]
       "font":["dist/fonts/glyphicons-halflings-regular.eot","dist/fonts/glyphicons-halflings-regular.eot","dist/fonts/glyphicons-halflings-regular.svg","dist/fonts/glyphicons-halflings-regular.ttf", "dist/fonts/glyphicons-halflings-regular.woff"]
    }
  },
  "main": "./dist/js/npm",
  "repository": {
    "type": "git",
    "url": "https://github.com/twbs/bootstrap.git"
  },
  "bugs": {
    "url": "https://github.com/twbs/bootstrap/issues"
  },
  "license": {
    "type": "MIT",
    "url": "https://github.com/twbs/bootstrap/blob/master/LICENSE"
  },

  "jspm": {
    "main": "js/bootstrap",
    "directories": {
      "example": "examples",
      "lib": "dist"
    },
    "shim": {
      "js/bootstrap": {
        "imports": "jquery",
        "exports": "$"
      }
    },
    "buildConfig": {
      "uglify": true
    }
  }
}

This could be even further extended to configure which assets are already "compiled", minified or packaged for usage or which assets are optional (bootstrap-theme.min.css).

Here are some very popular packages with js, css and/or other assets on npm without any further configuration:

Package Managers like bower, component, npm or other tools like browserify, etc. could use this information only or in addition to their separate configuration files.

What do you think?
cheers

Copy link

ghost commented Dec 31, 2014

It would be great if we could expand this spec with subarg syntax:
browserify/browserify#1046

@adjavaherian
Copy link

So this currently doesn't exist in Webpack?

@djfm
Copy link

djfm commented Jun 15, 2015

Nice spec.

When you write:

"browser": {
    "module-a": false,
    "./server/only.js": "./shims/server-only.js"
}

Are the relative paths in "./server/only.js": "./shims/server-only.js" relative to the location of the package.json file or to the directory of the file that calls require('./server/only.js')?

In other words, lets say root stands for the directory where the package.json is located and root/deep/file.js does require('./server/only.js'), should it resolve to:

  • root/deep/shims/server-only.js
  • or to root/shims/server-only.js?

@adjavaherian
Copy link

A regex option would be cool, so you don't have to explicitly define each module of type to be false.

@zeke
Copy link

zeke commented Sep 8, 2015

@balupton
Copy link

Is this added to anything besides browserify? Would be cool to see support in webpack and jspm.

@watsoncj
Copy link

Verified this works in webpack. The property is overloaded so you sometimes have to get creative if you have a client-only entry point and want to specify a module location.

"main": "index.js",
"browser": {
  "index.js": "bytebuffer/dist/ByteBufferAB.js",
  "Long": "bytebuffer/node_modules/long/dist/Long.js"
}

The index.js mapping is equivalent to "browser": "dist/ByteBufferAB.js"

@chauthai
Copy link

chauthai commented Oct 6, 2015

@balupton It's already supported in JSPM: jspm/jspm-cli#1062

@TotallyInformation
Copy link

This use of the browser property seems to be at odds with the npm specification? It seems dangerous to me and has already caused problems with the Axios package.

https://docs.npmjs.com/cli/v7/configuring-npm/package-json#browser

@ljharb
Copy link

ljharb commented Mar 7, 2021

It’s not at odds with it at all; they should be used in concert.

@TotallyInformation
Copy link

Sorry, not quite getting that. The npm docs appear to say that the browser property should contain a single string pointing to the main entry point for when the package is consumed by a browser. But this spec is using an object with a different meaning? How can that not be at odds? Am I missing something?

Having two wildly different specs on the same property makes it very much harder to use the property for anything unless you already know how a package is going to use it. Not much help when you are trying to automate things.

@ljharb
Copy link

ljharb commented Mar 22, 2021

Both are part of the browser field spec (the npm docs are not an authority on this subject). if a string, it replaces the “main”; if an object, it provides mappings to replace anything.

@TotallyInformation
Copy link

OK, can you please point me to the authoritative definition for the package.json file? Thanks.

@ljharb
Copy link

ljharb commented Mar 24, 2021

There is not one such definition, since many tools look at that file. For npm, it's https://docs.npmjs.com/cli/v7/configuring-npm/package-json/; for the "browser" field, it's https://github.com/defunctzombie/package-browser-field-spec.

@TotallyInformation
Copy link

Hmm, an interesting viewpoint. Not one I share I'm afraid. I see that we won't agree on this subject sadly. Having two different definitions for this field is confusing and counter-productive. As far as I am aware, npm created the package.json file and defined its schema including the browser property. If more flexibility was needed for that field, it should have been (and maybe was for all I know) raised with npm. What we have now is some scripts failing because of competing specifications for the field. Adding complexity and wasting people's time while they try to work out what is wrong.

Anyway, thanks for responding.

@ljharb
Copy link

ljharb commented Mar 27, 2021

You’re incorrect; npm did not create or define the browser field, they merely (partially) document it. If it’s confusing for you, I’m sure we could get npm to remove that, or link to the actual spec for it.

@TotallyInformation
Copy link

If that is the case then it would indeed be better for the npm documentation to be updated so that it is correct.

@basedwon
Copy link

basedwon commented May 7, 2022

It seems like this would be better if it followed the same conventions as the npm exports field? It doesn't seem to have any wildcard/regex abilities unless I'm missing something.

@ljharb
Copy link

ljharb commented May 7, 2022

The exports field has zero to do with npm; that’s a node-specific field that was added almost a decade after the browser field became a de facto standard.

@basedwon
Copy link

basedwon commented May 7, 2022

@ljharb I wasn't referring to the history of it - I just think it would be nice if the browser field allowed for pattern replacement so I don't have to input every filename into the package file. Maybe Webpack/Browserify should adopt the exports convention - that's all I'm saying. It would make for cleaner code.

The exports field does have the "browser" condition, but it doesn't seem like webpack or browserify pays attention to it.

@basedwon
Copy link

basedwon commented May 7, 2022

see the difference:

"exports": {
  ".": {
    "browser": "./lib/core.js",
    "node": "./lib/core-node.js"
  },
  "./*/": "./lib/*/",
  "./*": "./lib/*.js"
},
"browser": {
  ".": "./lib/core.js",
  "evented": "./lib/evented.js",
  "fig": "./lib/fig.js",
  "heap": "./lib/heap.js",
  "lock": "./lib/lock.js",
  "middle": "./lib/middle.js",
  "mixin": "./lib/mixin.js",
  "pipe": "./lib/pipe.js",
  "query": "./lib/query.js",
  "router": "./lib/router.js",
  "tree": "./lib/tree.js"
}

@basedwon
Copy link

basedwon commented May 7, 2022

Ok, it appears I was missing something. WP5 does have support for the exports field. Although I'm stuck with WP4 - but I found this plugin https://www.npmjs.com/package/@builder/exports-field-webpack-plugin will test and see how it goes

@basedwon
Copy link

basedwon commented May 7, 2022

That's a no-go -- tried it in Nuxt and it broke some things. Guess I'll just have to be verbose. Oh well ¯_(ツ)_/¯

@defunctzombie
Copy link
Author

The original idea behind the browser field is different from the exports field. With the browser field the purpose was not to wholesale ship a different set of files for node vs browser but instead provide a mechanism to replace a few files when packaging for browser. The thinking being that you would generally share 90% of the code and only replace a few compatibility or platform files. Ideally these wouldn't even be user-facing but could be.

@basedwon
Copy link

basedwon commented May 7, 2022

I'm building libraries that work in the browser and in Node. I get the original purpose of the browser field, but now that the browser is getting more advanced, the use cases are getting more advanced. WP5 is using the exports field with pattern replacement. I'm not sure about Browserify, but I'd like to make libs that work with both. It's not a huge deal, I can just define every file, but that definitely seems like an inefficient way to do it in the grand scheme

@ljharb
Copy link

ljharb commented May 7, 2022

The efficient thing to do is to have most of your files be universal, and have a very small number that vary by platform - ideally confined to separate packages.

@basedwon
Copy link

basedwon commented May 7, 2022

My files are isomorphic, meaning they work on both browser and in Node, I'd call that "universal". The issue is that Webpack (4) doesn't care, and so I have to compensate by listing every file in the browser field. I have one file that is used on Node only and the exports field handles that just fine.

The efficient thing would be to allow for the browser field to behave like the exports field. But less efficient for me to use my time trying to get that changed than just to deal with it. But as my libs grow, so too must the exports field. Tracking each import in the config is redundant and therefore inefficient. Hopefully Browserify/Webpack will address this. But I won't be holding my breath.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment