Skip to content

Commit

Permalink
docs: Move motivation under install and exports
Browse files Browse the repository at this point in the history
  • Loading branch information
@PuruVJ
PuruVJ committed Jun 25, 2024
1 parent cde7b47 commit 2fa57b8
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 31 deletions.
5 changes: 5 additions & 0 deletions .changeset/early-moles-hope.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"all-of-just": patch
---

docs: Move motivation under install and exports
62 changes: 31 additions & 31 deletions packages/pkg/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,36 +8,6 @@ Features:
- 🌳 **Tree Shakeable** - Library is fully tree-shakeable, meaning you may just never hit the 7.4KB mentioned above. If you're using only 3-4 functions from this library, chances are high you'll barely reach just **1KB**
- 🗃️ **Pre-bundled** - This package doesn't install any of the `just-` packages. Everything is pre-bundled in it, hence even downloading this package is fast and light on your storage.

# Motivation

The original library by Angus Croll is really amazing, being very small and modular. But the modular aspect is also its bane in today's world.

Why? The way we use the functions from the original library is by doing an `npm install just-[FUNCTION NAME]`. Which works just fine. But nowadays, we're more used to libraries like `date-fns`, which exposes all of it's functions in the root module only. The advantages of this pattern are:

1. **Install only once**: Only have to install once, means less trips to terminal, meaning less context switching, and small `package.json` and lock files.

2. **VSCode Auto import fully supported**: In today's world of VSCode auto import, opening terminal, typing `npm install just-[FUNCTION NAME]`, then coming back to code, and manually typing the imports is less than ideal. Auto import, on the other hand, has spoiled us really bad 😁. By having this monolithic pattern, you stay in code editor, you don't even have to go up to type imports, the function is available right there for you 🪄🪄

This library(`all-of-just`) strives to give a similar experience, at no added cost.

## Installation size?

When you install `all-of-just`, you're not downloading all the `just-*` packages, which along with their packaged `package.json` and `README.md` can be quite big when downloaded all at once. Rather, `all-of-just` bundles all of them together into a few JS files, along with proper TypeScript types. Your machine downloads no more than `62.5KB` while installing this library

## Assumptions

1. **You bring your own bundler and minifier** - This library is not optimized for direct use in browsers. it is spread over multiple files, and non-minified, and overall not ideal for direct usage in browser. It is recommended to have bundler/minifier toolchain set up to optimize and tree-shake this library.

2. **Using next gen bundler** - This one is not as critical for final performance, but it can greatly affect your developer experience

The original library was made in 2016. The scene at that time was very different from what is now. Then, with bundlers like webpack, you couldn't afford to use big libraries, hence why the original library is divided in so many small packages.

Now, we have tools like [Vite](https://vitejs.dev/), [Snowpack](https://www.snowpack.dev/), [WMR](https://wmr.dev/), which offer blazing fast compilation and Hot Module Reloading, and overall just super great dev experience. You could throw dependencies in the magnitudes of megabytes and your dev experience will still be blazing fast 🔥🔥.

Because of these modern tools, I can ship this larger library as one single package and your developer experience will still be really fast.

So the gist is: I assume you're using one of these next-gen bundlers, and not something traditional which rebundles every single thing on every reload, like Webpack/Grunt projects without HMR.

# Install

```sh
Expand Down Expand Up @@ -276,6 +246,36 @@ import {
} from 'all-of-just/functions';
```

# Motivation

The original library by Angus Croll is really amazing, being very small and modular. But the modular aspect is also its bane in today's world.

Why? The way we use the functions from the original library is by doing an `npm install just-[FUNCTION NAME]`. Which works just fine. But nowadays, we're more used to libraries like `date-fns`, which exposes all of it's functions in the root module only. The advantages of this pattern are:

1. **Install only once**: Only have to install once, means less trips to terminal, meaning less context switching, and small `package.json` and lock files.

2. **VSCode Auto import fully supported**: In today's world of VSCode auto import, opening terminal, typing `npm install just-[FUNCTION NAME]`, then coming back to code, and manually typing the imports is less than ideal. Auto import, on the other hand, has spoiled us really bad 😁. By having this monolithic pattern, you stay in code editor, you don't even have to go up to type imports, the function is available right there for you 🪄🪄

This library(`all-of-just`) strives to give a similar experience, at no added cost.

## Installation size?

When you install `all-of-just`, you're not downloading all the `just-*` packages, which along with their packaged `package.json` and `README.md` can be quite big when downloaded all at once. Rather, `all-of-just` bundles all of them together into a few JS files, along with proper TypeScript types. Your machine downloads no more than `62.5KB` while installing this library

## Assumptions

1. **You bring your own bundler and minifier** - This library is not optimized for direct use in browsers. it is spread over multiple files, and non-minified, and overall not ideal for direct usage in browser. It is recommended to have bundler/minifier toolchain set up to optimize and tree-shake this library.

2. **Using next gen bundler** - This one is not as critical for final performance, but it can greatly affect your developer experience

The original library was made in 2016. The scene at that time was very different from what is now. Then, with bundlers like webpack, you couldn't afford to use big libraries, hence why the original library is divided in so many small packages.

Now, we have tools like [Vite](https://vitejs.dev/), [Snowpack](https://www.snowpack.dev/), [WMR](https://wmr.dev/), which offer blazing fast compilation and Hot Module Reloading, and overall just super great dev experience. You could throw dependencies in the magnitudes of megabytes and your dev experience will still be blazing fast 🔥🔥.

Because of these modern tools, I can ship this larger library as one single package and your developer experience will still be really fast.

So the gist is: I assume you're using one of these next-gen bundlers, and not something traditional which rebundles every single thing on every reload, like Webpack/Grunt projects without HMR.

# Source of truth

`all-of-just` doesn't have any original code of its own. It export the different `just-*` packages as it is without adding any logic in between. And I intend to keep it that way. That way, this library is just a proxy to the original just library, which makes sure that `just` is improved regularly, and by extension, `all-of-just` too.
Expand All @@ -284,7 +284,7 @@ import {

1. This package has TypeScript definition for some packages.

2. Some of the packages that do have TypeScript support export more than the function, they export some additional types/functions too. However, to keep `all-of-just` simple, it don't export those types/functions. You'll need to install that package separately and import from it.
2. To keep `all-of-just` simple, it doesn't export extra types/functions. You'll need to install that package separately and import from it.

[MORE INFO](https://github.com/angus-c/just#typescript-)

Expand Down

0 comments on commit 2fa57b8

Please sign in to comment.