when publishing npm package, should I use src of dist - javascript

When publishing some javascript to npm as a library, should I set the "main" in pacakge.json to "dist/index.js" or my "src/index.js"?
Suppose that the library is built with webpack, and may be used with projects in webpack.
what will be the difference between two options. will webpack be able to do tree shaking in both options?
Thanks!

If your library is designed to be used in the browser, then it's important to remember that not everyone is using a module bundler.
It's good practice to set the main property to the bundled file (in your case dist/index.js) and make sure that you have a prepublish script that performs your build step before you publish it.
To support tree-shaking with bundlers like Rollup, you can use the module property and ensure that it points to a module that uses ES2015 imports.
For example:
{
"main": "dist/index.js",
"module": "src/index.js"
}
Rollup will respect this, but getting Webpack to tree-shake your code is a little more involved.

Related

.babelrc Babel configuration in a Next.js app

I'm getting my hands dirty with Babel for the 1st time to convert Jest tests from ES6 syntax to commonJS; this will likely involve using the #babel/plugin-transform-modules-commonjs babel plugin which I'm trying to install in my Next.js project. Looking at this part of Babel's configuration docs, I see the term package pop up a lot.
Are package hierarchies a Babel convention, Node-defined feature, or part of base JavaScript itself? What exactly defines a package in this context, and where is there documentation for them? Is babel-jest a stable alternative to this problem?
Babel uses a package.json file to resolve module dependencies. A package is a collection of files which can be imported using the require() function. You can read more about packages in the Node.js documentation on packages.
There is no standard way to define a package hierarchy, but Babel does have some conventions for how to organize your files. You can read more about that in the Babel documentation on organizing your code. Babel-jest is a stable alternative to converting Jest tests from ES6 syntax to commonJS. It provides support for using babel-plugin-transform-modules-commonjs to convert your modules to CommonJS.
Specifically, in the context of the Babel documentation you mentioned, the word "package" refers to your application itself (which is also considered a package) as well as other applications contained within the same repository (in case you have a monorepo containing many applications).

Settings up postcss to use VH fix

I'm attempting to use PostCSS to fix the problem where 100vh doesn't account for the browser/navigation bar on mobile devices.
https://github.com/Faisal-Manzer/postcss-viewport-height-correction
The problem is, I have no idea how to set it up and the instructions assume I know how. I have very little experience with JavaScript and don't use any frameworks or know how to, I just do everything in VS Code with no plugins.
I installed the PostCSS extension in VS Code but am unsure what to do next.
The installation says:
"And then add this javascript to public/index.html (for React), or add to template.html (for Preact)."
I don't use React (I don't think?), so what do I do instead?
Then it says:
"Check you project for existed PostCSS config: postcss.config.js in the project root, "postcss" section in package.json or postcss in bundle config.
If you already use PostCSS, add the plugin to plugins list:"
Would postcss.config.js be in my root folder? Am I supposed to create this file?
It then says to do this:
module.exports = {
plugins: [
+ require('postcss-viewport-height-correction'),
require('autoprefixer')
]
}
I added that to my .js file (Or does it go in the css file?), and am getting an error "module is not defined."
Could someone walk me through this as if I had no idea what I'm doing and have only been using JavaScript and VS Code for a week? Because that's where I'm at.
I'm on Windows if that makes a difference.
Part of the instructions say to do:
npm install --save postcss-viewport-height-correction
I don't know where to enter this command. I've come across similar instructions several times, and looking up "How to do npm install" doesn't produce any results. I've largely been avoiding using frameworks and extensions and plugins with JavaScript because I can never figure out how to use them, and every guide I can find assumes I already know what it all means.
Might be a long winded answer, but I'll try to respond to everything.
PostCSS is a JS-based tool for transforming styles with JS plugins. Typically, you use it as a plugin into your front-end build tool such as Webpack, Rollup, etc. You can also use it as a CLI app, manually running your build.
I just do everything in VS Code with no plugins.
Which editor you use is irrelevant. How are you building this content? Is it just plain HTML and CSS files?
I installed the PostCSS extension in VS Code
That extension is just for getting your editor on the same page as your PostCSS config. For example, you might write some CSS with your PostCSS config that will look like totally invalid CSS to your editor, and it would throw errors at this. That extension ensures it follows the same altered rules as your CSS now does, since you're using a tool that changes the rules.
Would postcss.config.js be in my root folder? Am I supposed to create this file?
Yes
I added that to my .js file (Or does it go in the css file?), and am getting an error "module is not defined."
JS, but it's throwing errors because you need to install it
Part of the instructions say to do:
npm install --save postcss-viewport-height-correction
I don't know where to enter this command.
From your terminal. NPM (and Yarn, if you run across it) is a CLI tool for installing Node packages, like PostCSS here.
Here are the instructions for installing Node & NPM: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm

Including/bundling dependencies in npm library with webpack

I've used webpack for a few single page apps and am now trying to build an npm library to be used by some of those apps (and anyone else who might find it useful.)
I understand that peerDependencies in package.json and externals in the webpack config go together. If I'm writing an AngularJS plugin, I don't bundle angular, because the consumer should already have it installed and we want to work with whatever version they're using.
Where I'm confused is on how to include another library I don't expect the consumer to have. If I list it in dependencies and import it and don't include it in externals, webpack seems to bundle the other library with my code. I don't think this is what I want.
If I list it in dependencies and do include it in externals, it seems not to be available in the consumer unless I explicitly include it in the consumer, e.g. a script tag pointing to a CDN. It acts like a peerDependency, even though it isn't.
Is it possible to have have my library's dependencies installed by npm in the consumer app and available at runtime without a) bundling the dependency into my library or b) forcing consumers of the library to explicitly load an obscure package?

Publish Aurelia component on NPM?

We have built a small-ish application using Aurelia, and would like to be able to integrate the app into a larger codebase. For example, it may be desirable to publish the Aurelia app on NPM, so other projects could integrate our code.
How can we build/publish the Aurelia app, so that it can be instantiated in a larger JavaScript application?
Typically, you wouldn't publish an entire Aurelia application to NPM, rather you would push plugins to NPM.
The simplest way to learn how to do this is to follow the example of the various Aurelia repos. We build the code in to multiple formats, but the most important are AMD and CommonJS (which is more important for your company is dependent on what tooling your company is using). Once you've built the code, the next step is to make sure your package.json file is set up correctly. It's best to copy the example of what we're doing in our own repos.
I would start by looking at either the dialog plugin or the templating-resources plugin. Both of these show good examples of how to publish your Aurelia plugin to NPM, whether it is a public or private npm feed.
https://github.com/aurelia/dialog/blob/master/package.json
https://github.com/aurelia/templating-resources/blob/master/package.json
Both of these plugins are set up to support Webpack, JSPM/SystemJS, and the Aurelia CLI out of the box.
I totally agree with #Ashley in not publishing larger applications to the global NPM registry. The big advantage of it is the simplicity of all that small packages which can be used to build large applications.
If you feel you got some reusable code, put in an own package and publish it.
Anyway, to give you an answer which does not require you to publish your complete app: you can include a complete repository (which is probobly what you are lookig for) in a different application via NPM.
npm install git://github.com/somegit/hubrepo.git
Or directly via the package.json:
"dependencies": {
"private-repo": "git+ssh://git#github.com:somegit/hubrepo.git#v1.0.0",
}
You can also do something similiar e.g. using JSPM. This would be simply:
jspm install your-app=github:OrgOrUser/your-app#your-branch
If you are facing long relative paths in your imports now, depending on your tooling, you may be interested in something like e.g. Resolving require paths with webpack which shows how to alias relative paths.
Sources/Links:
How to install a private NPM module without my own registry?
npm install private github repositories by dependency in package.json

NPM: should I use one of my dependencies' dependencies, or should I explicitly install it into the project at the root level?

TL;DR Summary
(I'm using Lodash as an example here, but it could be any other package)
In addition to using Lodash for its own purposes, my application also needs to import JavaScript from an NPM package that I created. The JavaScript in this package relies on Lodash as well. It's possible that each codebase may have installed a different version of Lodash. If JavaScript in my application and JavaScript in the installed package both import the same Lodash functions, then I want to avoid having to bundle two different versions of the same function. I understand that NPM is able to resolve the dependencies and that nothing will break, but the size of my application's JavaScript bundle will continue to grow as each codebase uses functions from different versions of the same libraries. It sounds like the only way to keep the versions in sync is to continuously monitor them and upgrade manually when appropriate, or to use the version provided by the installed package directly, without ever installing it into my application's own package.json. Is doing the latter a bad idea and is there no better way?
Original Question
At my company, we've created a Git repository that houses most of our UI component code. This repository also contains a static site generator, which transforms our UI component code into a "living style guide" website. The purpose of this website is to document and showcase our UI components on the web (similar to how PatternLab works).
We also distribute this code via NPM, so that it can be shared across multiple projects. Each project installs the NPM module as a dependency, then imports the SASS and JavaScript files contained within. The JavaScript has been written in ES6 and has not been bundled or transpiled. We've intentionally chosen not to distribute browser-ready code. Instead, each project is responsible for compiling its own SASS and bundling/transpiling its own JavaScript.
Most of our UI component JavaScript is simple and does not depend on any third-party libraries, so it's easy to import into our projects. However, some of our newer, more complex components rely on NPM packages such as Lodash, which presents a problem.
Obviously, we need to install Lodash in order for the static site generator to showcase our Lodash-reliant components inside of a web browser. Similarly, projects that consume the NPM package will also need to install Lodash, in order to create instances of these same components. This forces us to install Lodash twice: once in the UI component project, then again in the project that consumes the NPM package. This is problematic because the two projects could potentially install different versions of Lodash, which could lead to compatibility issues and/or increase the size of our JavaScript bundle.
One solution that I've discovered is to include Lodash under dependencies instead of devDependencies, in the UI component project. This way, when external projects install the UI component NPM module, Lodash will be installed along with it. This gives the project "free" access to Lodash without needing to explicitly install it itself. This is possible because NPM installs packages in a single, flat directory hierarchy, so it doesn't seem to matter if your project installs a package directly or if one of its dependencies exposes it as a dependency in it's own package.json. This eliminates version conflicts, since you don't have to install the package twice.
My question is, does this violate NPM best practices or is this how NPM is intended to work? After reading the NPM documentation and Googling for answers, it doesn't seem like this should be a problem. However, if what I'm suggesting is a bad idea, how else can I accomplish what I'm trying to do?
Here's a quick visual aid:
main.js
node_modules/
lodash/
foo/
bar.js
node_modules/
lodash/
main.js imports and uses Lodash. It also imports foo/bar.js, which uses Lodash too, but a potentially different version. Both files are ES6. main.js gets bundled and transpiled before being sent to the browser.
if is something you are directly using you should specify it in your package.json. it will be installed anyways but this way it will ensure that if your dependency removes that package as a dependency your project won't break

Categories

Resources