Skip to content

Commit

Permalink
docs(rfcs): create packaging for npm registry (#19066)
Browse files Browse the repository at this point in the history
* docs(rfcs): create packaging for npm registry

Co-authored-by: Oleksandr Fediashov <alexander.mcgarret@gmail.com>
  • Loading branch information
Hotell and layershifter authored Aug 3, 2021
1 parent 31f949a commit 5948c4e
Showing 1 changed file with 202 additions and 0 deletions.
202 changes: 202 additions & 0 deletions rfcs/build-system/03-packaging-for-npm.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
# RFC: Packaging for npm registry

---

_List contributors to the proposal here: @hotell_

## Summary

> #### 💡 NOTE: This proposal/guide applies only for vNext packages and libraries using new DX
## Problem statement

We ship lot of unnecessary stuff to our consumers:

- story files
- source files
- various configurations and metadata
- others...

What we ship is driven by our current npm package setup, which looks like following:

**`<package>/.npmignore`**

```
*.api.json
*.config.js
*.log
*.nuspec
*.test.*
*.yml
.editorconfig
.eslintrc*
.eslintcache
.gitattributes
.gitignore
.vscode
coverage
dist/storybook
dist/*.stats.html
dist/*.stats.json
dist/demo
fabric-test*
gulpfile.js
images
index.html
jsconfig.json
node_modules
results
src/**/*
!src/**/examples/*.tsx
!src/**/docs/**/*.md
!src/**/*.types.ts
temp
tsconfig.json
tsd.json
tslint.json
typings
visualtests
```

> **NOTE:** data was acquired by running `npm pack --dry-run` in `packages/react-text`
**Packaged output:**

```
=== Tarball Details ===
name: @fluentui/react-text
version: 9.0.0-alpha.0
package size: 564.2 kB
unpacked size: 2.2 MB
total files: 1008
```

With manually removed `.cache` folder:

```
=== Tarball Details ===
name: @fluentui/react-text
version: 9.0.0-alpha.0
package size: 31.1 kB
unpacked size: 263.9 kB
total files: 518
```

## Detailed Design or Proposal

> **💡 NOTE:** This proposal/guide applies only for vNext packages and libraries using new DX
This is a living document that will describe various proposals that all aim to improve following common goals:

- packaging size to npm registry
- faster install/over the wire transfer/less bytes
- faster packages consumption/processing by consumers
- better security for consumers
- better tree-shaking capabilities

### 1. `.npmignore` cleanup

**`<package>/.npmignore`**

```sh
.cache/
.storybook/
.vscode/
coverage/
src/
bundle-size/
config/
temp/
e2e/
node_modules/
__fixtures__
__tests__

*.log
*.yml
*.test.*
*.spec.*
*.stories.*
*.api.json

# config files
.git*
*rc.*
*config.*
.eslint*
.editorconfig
.prettierignore
```

> **NOTE:** data was acquired by running `npm pack --dry-run` in `packages/react-text`
**Packaged output:**

```
=== Tarball Details ===
name: @fluentui/react-text
version: 9.0.0-alpha.0
package size: 24.7 kB
unpacked size: 172.8 kB
total files: 250
```

#### Pros

This approach significantly improves our current situation:

- simpler `npmignore` configuration / better maintenance
- only implementation is being shipped (no tests, stories)
- **52% less files**
- **21% smaller packed package size**

#### Cons

- none

#### Discarded Solutions

- using `"files"` withing `package.json`
- doesn't support exclusion patterns
- non explicit for human (if `files` property is used, some files will be automatically and always shipped)
- 2 sources of "truth" (`.npmignore` and `files`)

### 2. shipping only type definition rollup

> **NOTE:** to make this RFC more focused this will be covered in followup PR's if needed
#### Pros

- TBA

#### Cons

- TBA

### 3. shipping only rollup-ed(bundled) implementation files

> **NOTE:** to make this RFC more focused this will be covered in followup PR's if needed
#### Pros

- TBA

#### Cons

- TBA

### 4. package.json post-processing

> **NOTE:** to make this RFC more focused this will be covered in followup PR's if needed
#### Pros

- TBA

#### Cons

- TBA

## Open Issues

- https://github.com/microsoft/fluentui/issues/19042

0 comments on commit 5948c4e

Please sign in to comment.