stdlib-js
script tag.
- I would like to use ES Modules.
- Use an individual package's ES Module build.
- I would like to use a pre-built bundle (possibly via a CDN, such as [unpkg][unpkg] or [jsDelivr][jsdelivr]).
- Install (or consume via a CDN) an individual package's pre-built UMD browser bundle.
- I am interested in using a substantial amount of functionality found in a top-level stdlib namespace and don't want to separately install hundreds of individual packages (e.g., if building an on-line calculator application and wanting all of stdlib's math functionality).
- Install one or more top-level namespaces. Installing the entire project is likely unnecessary and will lead to slower installation times. Installing a top-level namespace is likely to mean installing functionality which will never be used; however, installing a top-level namespace is likely to be easier and less time-consuming than installing many individual packages separately.
When bundling, installing a top-level namespace should not be a concern, as individual functionality can still be independently required/imported. Project installation times may, however, be somewhat slower.
- I am building a [Node.js][node-js] server application.
- I am interested in using various functionality found in stdlib.
- Install individual packages. Installing the entire project is likely unnecessary and will lead to slower installation times.
- I would like to vendor stdlib functionality and avoid dependency trees.
- Install individual package UMD bundles.
- I am interested in using a substantial amount of functionality found in a top-level stdlib namespace and don't want to separately install hundreds of individual packages.
- Install one or more top-level namespaces. Installing the entire project is likely unnecessary and will lead to slower installation times. Installing a top-level namespace is likely to mean installing functionality which will never be used; however, installing a top-level namespace is likely to be easier and less time-consuming than installing many individual packages separately.
- I am using Deno.
- Import individual packages using pre-built Deno builds.
- I would like to use stdlib functionality in an [Observable][observable] notebook.
- Consume a pre-built browser bundles via a CDN, such as [unpkg][unpkg] or [jsDelivr][jsdelivr].
- I want to hack at stdlib, possibly even creating customized builds to link to platform-specific native libraries (such as Intel's MKL or some other numerical library).
- Install the project as a system library by cloning this repository and following the [installation][stdlib-development] instructions as described in the [development guide][stdlib-development].
### Complete Library
To install the entire project as a library or application dependency,
bash
$ npm install @stdlib/stdlib
Once installed, stdlib packages can be individually required/imported to minimize load times and decrease bundle sizes. For example, to use require
javascript
var ndarray = require( '@stdlib/ndarray/array' );
var arr = ndarray( [ [ 1, 2 ], [ 3, 4 ] ] );
// returns <ndarray>
and to use import
javascript
import ndarray from '@stdlib/ndarray/array';
var arr = ndarray( [ [ 1, 2 ], [ 3, 4 ] ] );
// returns <ndarray>
### Individual Packages
stdlib is designed to allow decomposition of the main project into individual packages which can be independently consumed. Accordingly, users of the project can avoid installing all project functionality and only install the exact functionality they need.
To install individual packages, replace forward slashes / after @stdlib/ with hyphens -. For example,
bash
$ npm install @stdlib/ndarray-array
Once installed, individual packages can be required/imported. For example, to use require
javascript
var ndarray = require( '@stdlib/ndarray-array' );
var arr = ndarray( [ [ 1, 2 ], [ 3, 4 ] ] );
// returns <ndarray>
and to use import
javascript
import ndarray from '@stdlib/ndarray-array';
var arr = ndarray( [ [ 1, 2 ], [ 3, 4 ] ] );
// returns <ndarray>
### Namespaces
stdlib is comprised of various top-level namespaces (i.e., collections of related functionality united by common themes). For example, to install all math functionality found in the top-level math namespace,
bash
$ npm install @stdlib/math
Once installed, packages within a top-level namespace can be individually required/imported to minimize load times and decrease bundle sizes. For example, to use require
javascript
var sin = require( '@stdlib/math/base/special/sin' );
var v = sin( 3.14 );
// returns <number>
and to use import
javascript
import sin from '@stdlib/math/base/special/sin';
var v = sin( 3.14 );
// returns <number>
Note: installing nested namespaces found within top-level namespaces (e.g., math/base) is not supported. Consider installing individual packages or the relevant top-level namespace.
### Command-line Utility
To install globally for use as a command-line utility and/or use the [REPL][@stdlib/repl],
bash
$ npm install -g @stdlib/stdlib
which will expose the stdlib command. For example, to see available sub-commands
bash
$ stdlib help
and to run the [REPL][@stdlib/repl]
bash
$ stdlib repl
### Environment Builds
#### ES Modules
To use ES Modules via a <script> tag, use ES Module builds available in each package's repository via a dedicated esm branch (e.g., see the [esm][@stdlib/math-base-special-erf-esm] branch for [@stdlib/math-base-special-erf][@stdlib/math-base-special-erf-esm]). For example,
html
<script type="module">
import linspace from 'https://cdn.jsdelivr.net/gh/stdlib-js/array-base-linspace@esm/index.mjs';
import erf from 'https://cdn.jsdelivr.net/gh/stdlib-js/math-base-special-erf@esm/index.mjs';
const x = linspace( -10.0, 10.0, 100 );
for ( let i = 0; i < x.length; i++ ) {
console.log( 'x: %d, erf(x): %d', x[ i ], erf( x[ i ] ) );
}
</script>
#### Deno
To use individual packages in Deno, use Deno builds available in each package's repository via a dedicated deno branch (e.g., see the [deno][@stdlib/ndarray-array-deno] branch for [@stdlib/ndarray-array][@stdlib/ndarray-array-deno]). For example,
javascript
import ndarray from 'https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-array@deno/mod.js';
var arr = ndarray( [ [ 1, 2 ], [ 3, 4 ] ] );
// returns <ndarray>
````
<a name="install_env_builds_jquery"></a>
#### jQuery-like Bundle
For those wanting a jQuery-like bundle, one can use pre-built distributable UMD bundles for use in browser environments or as shared ("vendored") libraries in server environments available in each package's repository via a dedicated `umd` branch. See sections [UMD](#install_env_builds_umd) and [Node.js](#install_env_builds_nodejs) for more details.
<a name="install_env_builds_umd"></a>
#### UMD
To use UMD bundles either via a `<script>` tag or in [Observable][observable], use UMD **browser builds** available in each package's repository via a dedicated `umd` branch (e.g., see the [`umd`][@stdlib/math-base-special-erf-umd] branch for [`@stdlib/math-base-special-erf`][@stdlib/math-base-special-erf-umd]). For example,
<!-- run-disable -->html
<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/stdlib-js/array-base-linspace@umd/browser.js"></script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/stdlib-js/math-base-special-erf@umd/browser.js"></script>
<script type="text/javascript">
(function () {
var x = linspace( -10.0, 10.0, 100 );
for ( var i = 0; i < x.length; i++ ) {
console.log( 'x: %d, erf(x): %d', x[ i ], erf( x[ i ] ) );
}
})();
</script>
<a name="install_env_builds_nodejs"></a>
#### Node.js
To **vendor** stdlib functionality and avoid installing dependency trees, use UMD **server builds** available in each package's repository via a dedicated `umd` branch (e.g., see the [`umd`][@stdlib/math-base-special-erf-umd] branch for [`@stdlib/math-base-special-erf`][@stdlib/math-base-special-erf-umd]). For example,
<!-- run-disable -->javascript
var linspace = require( '/path/to/vendor/umd/@stdlib/array-base-linspace' );
var erf = require( '/path/to/vendor/umd/@stdlib/math-base-special-erf' );
var x = linspace( -10.0, 10.0, 100 );
for ( var i = 0; i < x.length; i++ ) {
console.log( 'x: %d, erf(x): %d', x[ i ], erf( x[ i ] ) );
}
<a name="install_custom_bundles"></a>
### Custom Bundles
To create a custom bundle based on project needs,
1. follow the [download][stdlib-development], [configuration][stdlib-development], and [installation][stdlib-development] instructions as described in the [development guide][stdlib-development].
2. navigate to the local installation directory.
3. run the following command to print help documentation for providing a list of stdlib package names to bundle
<!-- run-disable -->bash
$ NODE_PATH=./lib/node_modules node ./bin/cli bundle-pkg-list -- -h
4. modify and run the above command with the list of packages to bundle
<!-- run-disable -->bash
$ NODE_PATH=./lib/node_modules node ./bin/cli bundle-pkg-list -- <pkg> <pkg> <pkg> ...
<!-- FIXME: the following is not possible atm as we don't publish `@stdlib/_tools` which is needed in order for the command-line utility to work!
Alternatively, install stdlib as a command-line utility (as described above) and run the following command
-->
<!-- run-disable -->
<!--bash
$ stdlib bundle-pkg-list -- <pkg> <pkg> <pkg> ...
``
-->
Upon generating a bundle, the bundle can be loaded via a<script>` tag as described above for pre-built distributable UMD bundles.
### System Library
To install as a system library (e.g., for the purposes of creating custom builds), follow the [download][stdlib-development], [configuration][stdlib-development], and [installation][stdlib-development] instructions as described in the [development guide][stdlib-development].
## Prerequisites
Installing and running stdlib for use in [Node.js][node-js] requires the following prerequisites:
- [Node.js][node-js]: JavaScript runtime (version >= 0.10)
- [npm][npm]: package manager (version > 2.7.0; if Node < 1.0.0, version > 2.7.0 and < 4.0.0; if Node <= 10.x.x, version > 2.7.0 and < 6.0.0)
Most functionality in stdlib is implemented in JavaScript and no further prerequisites are required to use stdlib (i.e., you can safely avoid installing any additional prerequisites); however, some implementations try to capture performance benefits by using [native bindings][node-js-add-ons] and/or [WebAssembly][webassembly]. While not required to run stdlib, as every stdlib implementation has a JavaScript fallback, the following dependencies are required for building native add-ons, including linking to BLAS and LAPACK libraries:
- [GNU make][make]: development utility and task runner
- [GNU bash][bash]: an sh-compatible shell
- [gcc & g++][gcc] or [Clang][clang]: C/C++ compilation and linking (g++ version >= 4.8; clang version >= 3.5, Xcode version >=8.3.1 on OS X)
- [gfortran][gfortran]: Fortran compilation and linking (version >= 4.8)
While not required to run stdlib, the following dependencies are required for automatically downloading external libraries:
- [curl][curl], [wget][wget], or [fetch][fetch] (FreeBSD): utilities for downloading remote resources
The following external libraries can be automatically downloaded and compiled from source using make:
- [OpenBLAS][openblas]: optimized BLAS library
- [Electron][electron]: framework for cross-platform desktop applications
## Contributing
First time contributor?
- See the [contributing guidelines][stdlib-contributing].
Already an expert?
- Fork the repository.
- Clone the forked repository
bash
$ git clone --depth=1 https://github.com/<username>/stdlib.git
where <username> is your GitHub username.
- Navigate to the stdlib directory
bash
$ cd stdlib
- Install dependencies
bash
$ make install-node-modules
- Initialize your stdlib development environment
bash
$ make init
<!-- Project sponsors. If sponsors are included, add a horizontal rule before the section. Make sure to keep an empty line after the section element and another before the /section close. -->
Governance
For information about the governance of the stdlib project, see [GOVERNANCE.md][stdlib-governance].
License
See [LICENSE][stdlib-license].
Copyright
Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors].
