[docs] Import guide

Author: jamesgpearce

site/guides/1_the_basics/1_getting_started.md

@@ -82,4 +82,9 @@ If that all worked, you are set up and ready to learn more about TinyBase! From
 here on, we will mostly show Node-based code snippets, but most should be easily
 translatable to run in a browser too.
 
+Before we move on, you should be aware that the overall package includes a
+number of different versions of TinyBase, transpiled for different targets and
+formats. You may want to take a look at the Importing TinyBase guide if the code
+above isn't working in your environment - React Native in particular.
+
 Let's move onto the Creating A Store guide.

site/guides/1_the_basics/6_transactions.md

@@ -108,5 +108,5 @@ console.log(store.getTables());
 We've covered all of the essential basics of working with a TinyBase Store, but
 that's still just the start!
 
-Next we will show how you can quickly build user interfaces on top of a Store,
-and for that, it's time to proceed to the Building UIs guide.
+Before we move on, we have a quick aside about how to use various flavors of
+TinyBase in your app, in the Importing TinyBase guide.

site/guides/1_the_basics/7_importing_tinybase.md

@@ -0,0 +1,64 @@
+# Importing TinyBase
+
+This guide provides a quick aside about importing TinyBase into your
+application.
+
+## Targets and formats
+
+The overall package includes a number of different versions of TinyBase,
+transpiled for different targets and formats. You'll find them all in the
+`./lib` folder of the package, and you can directly import them as follows:
+
+| Directory   | Target | Format | Minified | Import                               |
+| ----------- | ------ | ------ | -------- | ------------------------------------ |
+| lib         | esnext | esm    | yes      | `import {...} from tinybase`         |
+| lib/debug   | esnext | esm    | no       | `import {...} from tinybase/debug`   |
+| lib/umd     | esnext | umd    | yes      | `import {...} from tinybase/umd`     |
+| lib/cjs     | esnext | cjs    | yes      | `import {...} from tinybase/cjs`     |
+| lib/es6     | es6    | esm    | yes      | `import {...} from tinybase/es6`     |
+| lib/umd-es6 | es6    | umd    | yes      | `import {...} from tinybase/umd-es6` |
+| lib/cjs-es6 | es6    | cjs    | yes      | `import {...} from tinybase/cjs-es6` |
+
+## Using TinyBase submodules
+
+The tinybase module is the master package of all the functionality together
+(except the ui-react module and tools module, which always remain standalone
+options). Since many of the submodules share compiled-in dependencies, the
+master package is smaller to include than including all of the submodules
+separately.
+
+However, for a very minimal set of submodules, you may save size by including
+them piecemeal. If you only wanted a Store and a Metrics object, for example,
+you could import them alone like this:
+
+```js yolo
+import {createStore} from 'tinybase/store';
+import {createMetrics} from 'tinybase/metrics';
+// ...
+```
+
+You can also import single packages in other targets and formats. For example:
+
+```js yolo
+import {createStore} from 'tinybase/es6/store';
+import {createMetrics} from 'tinybase/es6/metrics';
+import {useCell} from 'tinybase/es6/ui-react';
+// ...
+```
+
+## React Native
+
+If you are using [React Native](https://reactnative.dev/) - for example with
+[Expo](https://expo.dev/) - be aware that the
+[Metro](https://facebook.github.io/metro/) bundler does not currently support
+module resolution very well. You may have to add in the `lib` portion of the
+path to be explicit about your imports:
+
+```js yolo
+import {createStore} from 'tinybase/lib';
+import {useCell} from 'tinybase/lib/ui-react';
+```
+
+OK, enough with the `import` shenanigans. Next we will show how you can quickly
+build user interfaces on top of a Store, and for that, it's time to proceed to
+the Building UIs guide.

site/guides/2_building_uis/1_getting_started_with_ui_react.md

@@ -44,5 +44,17 @@ are merely to support JSX in the browser and for the purposes of illustrating
 how to get started quickly. In a production environment you should pre-compile
 and your JSX and modules to create a bundled browser app.
 
-Let's first understand how to use hooks in the ui-react module, and move on to
-the Using React Hooks guide.
+If you're bundling the whole app, you can of course import the ui-react module
+something like this:
+
+```js yolo
+import {createStore} from 'tinybase';
+import {CellView} from 'tinybase/ui-react';
+// ...
+```
+
+(You can also select different targets and flavors of the ui-react module as
+described in the Importing TinyBase guide.)
+
+Boilerplate aside, let's move on to understand how to use hooks in the ui-react
+module, with the Using React Hooks guide.

site/guides/8_how_tinybase_is_built/2_architecture.md

@@ -64,11 +64,11 @@ the `.d.ts` type definitions, the compiled `.js` files, and their compressed
 submodules.
 
 The `tinybase.js` and `tinybase.js.gz` files represent the master package of
-everything together (except the ui-react module, which always remains a
-standalone option). Since many of the submodules share compiled-in dependencies,
-the master package is smaller to include than including all of the submodules
-separately. However, for a very minimal set of modules, you may save size by
-including them piecemeal.
+everything together (except the ui-react module and tools module, which always
+remain standalone options). Since many of the submodules share compiled-in
+dependencies, the master package is smaller to include than including all of the
+submodules separately. However, for a very minimal set of modules, you may save
+size by including them piecemeal.
 
 In the root of the `lib` directory, all of these files are built to the
 [`esnext`](https://esbuild.github.io/api/#target) target and the
@@ -77,13 +77,14 @@ are subdirectories that contain builds of different types:
 
 | Directory | Target | Format | Minified |
 | --------- | ------ | ------ | -------- |
-| .         | esnext | esm    | true     |
-| ./debug   | esnext | esm    | false    |
-| ./umd     | esnext | umd    | true     |
-| ./cjs     | esnext | cjs    | true     |
-| ./es6     | es6    | esm    | true     |
-| ./umd-es6 | es6    | umd    | true     |
-| ./cjs-es6 | es6    | cjs    | true     |
+| .         | esnext | esm    | yes      |
+| ./debug   | esnext | esm    | no       |
+| ./umd     | esnext | umd    | yes      |
+| ./cjs     | esnext | cjs    | yes      |
+| ./es6     | es6    | esm    | yes      |
+| ./umd-es6 | es6    | umd    | yes      |
+| ./cjs-es6 | es6    | cjs    | yes      |
 
 These build configurations are all defined in the `compileForProd` task in
-`gulpfile.mjs`.
+`gulpfile.mjs`, and instructions for importing them are in the Importing
+TinyBase guide.