aljaz/pear-docs
1
0
Fork 0
mirror of https://github.com/aljazceru/pear-docs.git synced 2025-12-18 15:04:26 +01:00
Code Issues Packages Projects Releases Wiki Activity

move bare ref and update links (#93)

Browse Source 
* move bare ref and update links

* move pear ref into subfolder

* update README

* tiny fix

---------

Co-authored-by: Vivek Singh <vivek@peartree.to>
This commit is contained in:
Vivek Singh
2024-03-21 17:36:09 +05:30
committed by rafapaezbas
parent ee31b5b5e9
commit b339e2878a
11 changed files with 14 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
reference/bare/bare-modules.md Normal file
View File

@@ -0,0 +1,186 @@
# Bare Modules
Bare modules provide a robust system for managing code dependencies within Bare applications. This section delves into the details of Bare's module system.
```
npm i bare-module
```
## Usage
```js
const Module = require('bare-module')
````
## External Modules for Bare
Supported Modules |
:--- |
<https://github.com/holepunchto/bare-abort>
<https://github.com/holepunchto/bare-assert>
<https://github.com/holepunchto/bare-atomics>
<https://github.com/holepunchto/bare-buffer>
<https://github.com/holepunchto/bare-bundle>
<https://github.com/holepunchto/bare-channel>
<https://github.com/holepunchto/bare-console>
<https://github.com/holepunchto/bare-env>
<https://github.com/holepunchto/bare-events>
<https://github.com/holepunchto/bare-fs>
<https://github.com/holepunchto/bare-hrtime>
<https://github.com/holepunchto/bare-http1>
<https://github.com/holepunchto/bare-inspect>
<https://github.com/holepunchto/bare-module>
<https://github.com/holepunchto/bare-os>
<https://github.com/holepunchto/bare-path>
<https://github.com/holepunchto/bare-pipe>
<https://github.com/holepunchto/bare-process>
<https://github.com/holepunchto/bare-readline>
<https://github.com/holepunchto/bare-repl>
<https://github.com/holepunchto/bare-signals>
<https://github.com/holepunchto/bare-subprocess>
<https://github.com/holepunchto/bare-timers>
<https://github.com/holepunchto/bare-tty>
<https://github.com/holepunchto/bare-url>
## Packages
A package is directory with a `package.json` file.
### Fields
#### `"name"`
```json
{
"name": "my-package"
}
```
The name of the package. This is used for [addon resolution](https://github.com/holepunchto/bare-addon-resolve#algorithm), [self-referencing](#self-referencing), and importing packages by name.
#### `"version"`
```json
{
"version": "1.2.3"
}
```
The current version of the package. This is used for [addon resolution](https://github.com/holepunchto/bare-addon-resolve#algorithm).
#### `"type"`
```json
{
"type": "module"
}
```
The module format used for `.js` files. If not defined, `.js` files are interpreted as CommonJS. If set to `"module"` the `.js` files are instead interpreted as ES modules.
#### `"exports"`
```json
{
"exports": {
".": "./index.js"
}
}
```
The entry points of the package. If defined, only the modules explicitly exported by the package may be imported when importing the package by name.
##### Subpath exports
A package may define more than one entry point by declaring several subpaths with the main export being `"."`:
```json
{
"exports": {
".": "./index.js",
"./submodule": "./lib/submodule.js"
}
}
```
When importing the package by name, `require('my-package')` will resolve to `<modules>/my-package/index.js` whereas `require('my-package/submodule')` will resolve to `<modules>/my-package/lib/submodule.js`.
##### Conditional exports
Conditional exports allow packages to provide different exports for different conditions, such as the module format of the importing module:
```json
{
"exports": {
".": {
"import": "./index.mjs",
"require": "./index.cjs"
}
}
}
```
When importing the package by name, `require('my-package')` will resolve to `<modules>/my-package/index.cjs` whereas `import 'my-package'` will resolve to `<modules>/my-package/index.mjs`.
Similarly, conditional exports can be used to provide different entry points for different runtimes:
```json
{
"exports": {
".": {
"bare": "./bare.js",
"node": "./node.js"
}
}
}
```
To provide a fallback for when no other conditions match, the `"default"` condition can be declared:
```json
{
"exports": {
".": {
"bare": "./bare.js",
"node": "./node.js",
"default": "./fallback.js"
}
}
}
```
The following conditions are supported, listed in order from most specific to least specific as conditions should be defined:
Condition | Description
:-- | :--
`"bare"` | This applies when the module is being imported from another Bare module.
`"node"` | This applies when the module is being imported within a Node.js environment.
`"import"` | This applies when the module is being imported using an ES module import statement.
`"require"` | This applies when the module is being imported using the CommonJS require() function.
`"default"` | This serves as a fallback export if none of the more specific conditions (bare, node, import, require) are met.
##### Self-referencing
Within a package, exports defined in the `"exports"` field can be referenced by importing the package by name. For example, given the following `package.json`...
```json
{
"name": "my-package",
"exports": {
".": "./index.js",
"./submodule": "./lib/submodule.js"
}
}
```
...any module within `my-package` may reference these entry points using either `require('my-package')` or `require('my-package/submodule')`.
##### Exports sugar
If a package defines only a single export, `"."`, it may leave out the subpath entirely:
```json
{
"exports": "./index.js"
}
```