simple-squiggle

A restricted subset of Squiggle
Log | Files | Refs | README

custom_bundling.md (4073B)

      1 # Custom bundling
      2 
      3 Math.js is a large library containing many data types and functions.
      4 It is well possible that you only need a small portion of the library.
      5 Math.js allows for picking just the functions and data types you need.
      6 This gives faster load times and smaller browser bundles. Math.js uses
      7 ES modules, and creating small bundles using tree-shaking works out of
      8 the box when using Webpack for example.
      9 
     10 This page describes:
     11 
     12 - How to use just a few functions for faster load times and smaller bundles.
     13 - How to use light-weight, number only implementations of functions.
     14 - What to expect from bundle sizes when using tree-shaking.
     15 
     16 ## Using just a few functions
     17 
     18 Using the function `create`, a mathjs instance can be created.
     19 The `all` object contains all functionality available in mathjs,
     20 and a mathjs instance containing everything can be created like:
     21 
     22 ```js
     23 import { create, all } from 'mathjs'
     24 
     25 const math = create(all)
     26 ```
     27 
     28 To create an instance with just a few functions, you have to pass the
     29 factory functions of the functions you need, and all their dependencies.
     30 For example the function `add` depends on the functions `addScalar`,
     31 `equalScalar`, classes `DenseMatrix` and `SparseMatrix`, and more.
     32 Because it is hard to figure out what the dependencies of a function are,
     33 and the dependencies of the dependencies, mathjs provides ready made
     34 collections of all dependencies for every function. For example all
     35 factory functions of function `add` and its dependencies are available
     36 as `addDependencies`.
     37 
     38 Here is a full example of loading just a few functions in a mathjs instance:
     39 
     40 ```js
     41 // file: custom_loading.js
     42 
     43 import {
     44   create,
     45   fractionDependencies,
     46   addDependencies,
     47   divideDependencies,
     48   formatDependencies
     49 } from 'mathjs'
     50 
     51 const config = {
     52   // optionally, you can specify configuration
     53 }
     54 
     55 // Create just the functions we need
     56 const { fraction, add, divide, format } = create({
     57   fractionDependencies,
     58   addDependencies,
     59   divideDependencies,
     60   formatDependencies
     61 }, config)
     62 
     63 // Use the created functions
     64 const a = fraction(1, 3)
     65 const b = fraction(3, 7)
     66 const c = add(a, b)
     67 const d = divide(a, b)
     68 console.log('c =', format(c)) // outputs "c = 16/21"
     69 console.log('d =', format(d)) // outputs "d = 7/9"
     70 ```
     71 
     72 This example can be bundled using for example Webpack:
     73 
     74 ```
     75 npx webpack custom_loading.js -o custom_loading.bundle.js --mode=production
     76 ```
     77 
     78 Only the used parts of mathjs will be bundled thanks to tree-shaking.
     79 
     80 
     81 ## Numbers only
     82 
     83 The functions of mathjs support multiple data types out of the box, like
     84 numbers, bignumbers, complex numbers, units, and matrices. Quite commonly however,
     85 only support for numbers is needed and the other data-types are overkill.
     86 
     87 To accomodate for this use case of only numbers only, mathjs offers light-weight,
     88 number only implementations of all relevant functions. These are available by
     89 importing from `'mathjs/number'` instead of `'mathjs'`:
     90 
     91 ```js
     92 // use light-weight, numbers only implementations of functions
     93 import { create, all } from 'mathjs/number'
     94 
     95 const math = create(all)
     96 console.log(add(2, 3)) // 5
     97 ```
     98 
     99 ## Bundle size
    100 
    101 When using just a few functions of mathjs instead of the whole library,
    102 you may expect the size of the bundle to be just a small fraction of the
    103 complete library. However, to create the function `add` supporting all data
    104 types, all these data types must be included: Unit, BigNumber, Complex,
    105 DenseMatrix, SparseMatrix, etc. A rough idea of the size of different parts of
    106 mathjs:
    107 
    108 - About 5% is coming from core functionality like `create`, `import`, `factory`,
    109   `typed-function`, etc.
    110 - About 30% of the bundle size comes from the data classes `Complex`, `BigNumber`, `Fraction`, `Unit`, `SparseMatrix`, `DenseMatrix`.
    111 - About 25%  of the bundle size comes from the expression parser.
    112   Half of this comes from the embedded docs.
    113 - About 40% comes from the about 200 built-in functions and some constants.
    114 
    115 To get a better insight in what is in your JavaScript bundle, you can use
    116 a tool like [source-map-explorer](https://github.com/danvk/source-map-explorer).