LumeWeb
/
filer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: remove buffer shim docs and replace with info on why it's not provided

This commit is contained in:
Ben Heidemann 2021-04-10 11:00:18 +01:00 committed by David Humphrey
parent 1f02edf5b3
commit 0db08e31bb
1 changed files with 16 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
README.md
View File

@ -56,10 +56,10 @@ var Filer = window.Filer;
### Webpack Plugin ### Webpack Plugin
Filer can be used as a drop-in replacement for the node.js [fs](http://nodejs.org/api/fs.html), Filer can be used as a drop-in replacement for the node.js [fs](http://nodejs.org/api/fs.html) and
[path](http://nodejs.org/api/path.html) and [buffer](http://nodejs.org/api/buffer.html) modules. [path](http://nodejs.org/api/path.html) modules. For convenience, filer provides a webpack plugin which
For convenience, filer provides a webpack plugin which will shim the desired node.js functionality. will shim the desired node.js functionality. This plugin can be used by inserting the following into
This plugin can be used by inserting the following into your webpack config: your webpack config:
```javascript ```javascript
// webpack.config.js // webpack.config.js
@ -72,21 +72,19 @@ module.exports = {
} }
``` ```
You can then import the node.js [fs](http://nodejs.org/api/fs.html), You can then import the node.js [fs](http://nodejs.org/api/fs.html) and [path](http://nodejs.org/api/path.html)
[path](http://nodejs.org/api/path.html) and [buffer](http://nodejs.org/api/buffer.html) modules as normal modules as normal and FilerWebpackPlugin will ensure that webpack will resolve references to these modules to
and FilerWebpackPlugin will ensure that webpack will resolve references to these modules to the appropriate the appropriate filer shims. You will then be able to use these modules as normal (with the exception of the
filer shims. You will then be able to use these modules as normal (with the exception of the synchronous fs synchronous fs methods e.g. `mkdirSync()`).
methods e.g. `mkdirSync()`).
```javascript ```javascript
import fs from 'fs'; import fs from 'fs';
import path from 'path'; import path from 'path';
import { Buffer } from 'buffer';
``` ```
The filer webpack plugin will, by default, shim the [fs](http://nodejs.org/api/fs.html), The filer webpack plugin will, by default, shim the [fs](http://nodejs.org/api/fs.html) and
[path](http://nodejs.org/api/path.html) and [buffer](http://nodejs.org/api/buffer.html) modules. However, [path](http://nodejs.org/api/path.html) modules. However, it's behaviour can be customised by passing an
it's behaviour can be customised by passing an options object. options object.
```javascript ```javascript
// webpack.config.js // webpack.config.js
@ -105,38 +103,17 @@ The following options can be passed to the filer webpack plugin:
|---------------|---------|----------|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| |---------------|---------|----------|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| filerDir | string | yes | '\<rootDir\>/node_modules/filer' | The directory in which filer is installed. | | filerDir | string | yes | '\<rootDir\>/node_modules/filer' | The directory in which filer is installed. |
| shimsDir | string | yes | '\<rootDir\>/node_modules/filer/shims' | The directory in which the shims are installed. | | shimsDir | string | yes | '\<rootDir\>/node_modules/filer/shims' | The directory in which the shims are installed. |
| fsProviderDir | string | yes | '\<rootDir\>/node_modules/filer/shims/providers' | The directory in which the shims are located. This option is required when using a custom provider. |
| shimFs | boolean | yes | true | Should the fs module be shimmed. | | shimFs | boolean | yes | true | Should the fs module be shimmed. |
| shimPath | boolean | yes | true | Should the path module be shimmed. | | shimPath | boolean | yes | true | Should the path module be shimmed. |
| shimBuffer | boolean | yes | true | Should the buffer module be shimmed. |
| fsProvider | string | yes | 'default' | The file system provider to use. Should be one of 'default', 'indexeddb', 'memory', 'custom'. The 'default' option is equivalent to 'indexeddb'. | | fsProvider | string | yes | 'default' | The file system provider to use. Should be one of 'default', 'indexeddb', 'memory', 'custom'. The 'default' option is equivalent to 'indexeddb'. |
| fsProviderDir | string | yes | '\<rootDir\>/node_modules/filer/shims/providers' | The directory in which the shims are located. This option is required when using a custom provider. |
NOTE: '\<rootDir\>' will be resolved to the current working directory. NOTE: '\<rootDir\>' will be resolved to the current working directory.
The Buffer object is globally defined in a node environment and many third party libraries will not import (or require) it. Though filer also exposes the Buffer object, it is left up to the user to shim this as appropriate. This is because filer offers
Using the filer webpack plugin alone will be ineffective in such cases. Instead we must expand our webpack config to use webpacks no custom implementation. Currently, filer uses the [node-libs-browser](https://github.com/webpack/node-libs-browser) Buffer implementation
[provide plugin](https://webpack.js.org/plugins/provide-plugin/), which will automatically load the module without the need for an import internally, though any faithful implementation of the [node.js Buffer object](http://nodejs.org/api/buffer.html) should play nicely
or require. This can be implemented as follows: with filer.
```javascript
// webpack.config.js
var filer = require('filer');
var webpack = require('webpack');
module.exports = {
plugins: [
new filer.FilerWebpackPlugin({
shimBuffer: true,
}),
new webpack.ProvidePlugin({
Buffer: ['buffer', 'Buffer'],
}),
]
}
```
This will, in effect, make the Buffer object shim globally available in the same way that the node.js
[Buffer object](http://nodejs.org/api/buffer.html) is in a node environment.
### Getting Started ### Getting Started