Skip to content

Commit 64a205a

Browse files
author
Harrison Ifeanyichukwu
committed
feat: Add clear project documentation, how to contribute note, and project maintainers footer
1 parent 819448e commit 64a205a

File tree

1 file changed

+105
-55
lines changed

1 file changed

+105
-55
lines changed

‎README.md

Lines changed: 105 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,15 @@
44
[![Coverage Status](https://coveralls.io/repos/github/harrison-ifeanyichukwu/rollup-all/badge.svg?branch=master)](https://coveralls.io/github/harrison-ifeanyichukwu/rollup-all?branch=master)
55
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
66
[![npm version](https://badge.fury.io/js/rollup-all.svg)](https://badge.fury.io/js/rollup-all)
7-
![npm](https://img.shields.io/npm/dw/rollu-up.svg)
7+
![npm](https://img.shields.io/npm/dw/rollup-all.svg)
88

99
## Overview
1010

1111
Rollup-all is a lightweight, extensive and configurable npm package for building all your ESNext source codes in one parse using [rollup.js](https://rollupjs.org/guide/en).
1212

13-
It enables you to generate separate project [lib and dist builds](https://stackoverflow.com/questions/39553079/difference-between-lib-and-dist-folders-when-packaging-library-using-webpack) using any of the supported [rollup.js build formats](https://rollupjs.org/guide/en#big-list-of-options).
13+
It enables you to generate separate project [lib and dist builds](https://stackoverflow.com/questions/39553079/difference-between-lib-and-dist-folders-when-packaging-library-using-webpack) using any of the supported [rollup.js build formats](https://rollupjs.org/guide/en#big-list-of-options) including support for minified build version.
1414

15-
It also allows you to configure the build process, letting you define what should be included and excluded in the build, if sourcemap should be generated, if minified or only minified versions of the build should be generated, and lots more.
16-
17-
These options are achieved when you create and place an optional [.buildrc.json](BUILDRC_CONFIG.md) in your project root diretory. You may even name it anything or place it in any other path, so long as you provide the file's relative path during the [api call](#getting_started).
15+
It allows you to configure the build process, letting you define what should be included and excluded in the build, if sourcemap should be generated, if minified or only minified versions of the build should be generated, and lots more...
1816

1917
## Getting Started
2018

@@ -30,7 +28,7 @@ npm install it:
3028
npm install --save-dev rollup-all
3129
```
3230

33-
Modify `rollup.config.js` file as like shown below:
31+
To start using the module, you have to modify your project's `rollup.config.js` file as like shown below, calling the api:
3432

3533
```javascript
3634
/**
@@ -71,6 +69,8 @@ let configPath = '';
7169
export default rollupAll.getExports(uglifier(), plugins, configPath);
7270
```
7371

72+
> **Note**: if you are not using any uglifier plugin, passin null as the first parameter. Note also that you must execute all plugins before passing it to the api call.
73+
7474
## How It Works
7575

7676
Rollup-all uses an internal `.buildrc.json` file that defines default build configurations for your project. the full config options is as shown below:
@@ -115,78 +115,128 @@ Rollup-all uses an internal `.buildrc.json` file that defines default build conf
115115
}
116116
```
117117

118+
You can override these options by creating and placing a `.buildrc.json` file right in your project root directory. You can even name it any other thing or place it anywhere provided you supply the file's relative path as a third parameter during the [api call](#getting-started).
119+
118120
## Working with Config Options
119121

120-
You can override these options by creating and placing a `.buildrc.json` file right in your project root directory. You can even name it any other thing or place it anywhere provided you supply the file's relative path as a third parameter during the [api call](#getting_started).
122+
The config options has three sections:
121123

122-
The following config options shown below can be defined specifically on the distConfig or libConfig section, hence, overriding their global counterpaths:
124+
1. Global config options
123125

124-
```json
125-
{
126-
"exclude": [],
126+
2. Dist specific build options
127127

128-
"include": ["*"],
128+
3. Lib specific build options
129129

130-
"copyAssets": false,
130+
These makes it easy to similar build options in the global section and different build options that are specific for each build kind.
131131

132-
"uglify": false,
132+
### Config Options Explained
133133

134-
"uglifyOnly": false,
134+
> note that options with asterisk can be defined specifically on the `distConfig` or `libConfig` sections.
135135
136-
"interop": false,
136+
- **srcDir**: defines the relative path to your project's source folder. Defaults to `src`.
137137

138-
"sourcemap": true
139-
}
140-
```
138+
- **mainModuleFileName**: defines the projects main file name such as `index.js`, `main.js`, `entry.js`. Defaults to `main.js`.
141139

142-
### Specifying externalModules
140+
- **mainModuleName**: defines the globally exposed module name. this applies specifically to projects that has `iife` dist builds. e.g, `JQuery` for jquery, `React` for react, `FJS` for forensic-js, etc.
143141

144-
To specify external modules that your project uses, and that should not be bundled into your build, such as node.js inbuilt packages, and other third party npm packages, we can do it like below:
142+
- **fileExtensions**: defines an array of project src code file extensions, such as `.jsx`, `.js` etc. Defaults to `[".js"]`. Every other file within the src directory are regarded as asset files.
145143

146-
```json
147-
{
148-
"externalModules": ["fs", "path", "crypto", "lodash"]
149-
}
150-
```
144+
- **externalModules**: defines a list of external modules used by library that should not bundled into your build. such as node.js inbuild packages. e.g [`"fs"`, `"path"`,...], etc. defaults to empty array.
151145

152-
### Disable a specific build
146+
- **exclude***: defines a list of modules to exclude from the build. This option can be defined specifically for a particular build as well. entries can be strings or regex. e.g `"src/modules/*.js"` ignores every .js file in the modules directory. `"src/**/*.js"` ignores all .js files in the src directory. `"*"` ignores all files. It defaults to an empty array.
153147

154-
Not all projects are meant to be have dist builds, some projects are only done for the node.js environment, and such should have only a lib build. We can disable the dist build as shown below:
148+
- **include***: defines a list of modules to include in the build. This option can be defined specifically for a particular build as well. entries can be strings or regex. Defaults to `["*"]`, which includes everything.
155149

156-
```json
157-
{
158-
"distConfig": {
159-
"disabled": true
150+
- **copyAssets***: defines if asset files should be copied over during the build process. Asset files are files whose extensions are not part of the **fileExtensions** entry options.
151+
152+
- **uglify***: defines if the build should produce minified versions too. minified versions has `.min` attached to their output file names. When set to true, you should also supply an uglifier plugin for it to work. It ignores the option if no uglifier plugin is supplied. Default value is `false`.
153+
154+
- **uglifyOnly***: defines if the build should produce only minified versions. minified versions has `.min` attached to their output file names. When set to true, you should also supply an uglifier plugin for it to work. It ignores the option if no uglifier plugin is supplied. Default value is `false`. **Note that no unminified build is produced if set to true**
155+
156+
- **interop***: defines if the `rollup.js` interop functionality should be enabled. Defuaults to `false`.
157+
158+
- **sourcemap***: defines if the build should produce source maps. value can be `true`, `"inline"` or `false`. Default value is `true` which causes source map files to be generated.
159+
160+
- **distConfig.outDir** - defines the output directory for your `dist` build. Defaults to `"dist"`.
161+
162+
- **distConfig.disabled** - defines if the module should not generate distributed build. Defaults to `false`.
163+
164+
- **distConfig.format** - defines the build format for the distributed code. Defaults to `"iife"`. Most distributed codes are always in the `"umd"` or `"iife"` browser friendly formats.
165+
166+
- **libConfig.outDir** - defines the output directory for your `library` build. Defaults to `"lib"`.
167+
168+
- **libConfig.disabled** - defines if the module should not generate library build. Defaults to `false`.
169+
170+
- **libConfig.format** - defines the build format for the library code. Defaults to `"cjs"`. Most library codes are always in the `"cjs"` format for node.js.
171+
172+
## Examples
173+
174+
- **Specifying externalModules**
175+
176+
```json
177+
{
178+
"externalModules": ["fs", "path", "crypto", "lodash"]
160179
}
161-
}
162-
```
180+
```
163181

164-
### Copy Asset file during Build
182+
- **Disabling dist build**
165183

166-
We can copy asset files that our modules use when running the build process as shown below:
184+
Not all projects are meant to be have distritubed builds, some projects are only done for the node.js environment, and such should have only a `lib` build. We can disable the dist build as shown below:
167185

168-
```json
169-
{
170-
"copyAssets": true,
171-
"distConfig": {
172-
"copyAssets": false
186+
```json
187+
{
188+
"distConfig": {
189+
"disabled": true
190+
}
173191
}
174-
}
175-
```
192+
```
176193

177-
### Generate Minified Builds Too
194+
- **Copying Asset files during Build**
178195

179-
We can also generate separate minified builds for all modules during the build process. Minified builds are named with `.min` format. We can even decide to generate only minified builds. You must pass in an [uglifier plugin](https://github.com/rollup/rollup/wiki/Plugins#output--prettifying) as first parameter to the API for this to work.
196+
We can copy asset files that our modules use when running the build process as shown below:
180197

181-
```json
182-
{
183-
"uglify": true,
184-
"uglifyOnly": true,
185-
"distConfig": {
186-
"uglify": false,
187-
"uglifyOnly": false
198+
```json
199+
{
200+
"distConfig": {
201+
"copyAssets": false
202+
},
203+
"libConfig" {
204+
"copyAssets": true
205+
}
188206
}
189-
}
190-
```
207+
```
208+
209+
- **Generating minified builds**
210+
211+
We can also generate separate minified builds for all modules during the build process. Minified builds are named with `.min` format. We can even decide to generate only minified builds. You must pass in an [uglifier plugin](https://github.com/rollup/rollup/wiki/Plugins#output--prettifying) as first parameter to the API for this to work. Below, we uglify only the `dist` build.
212+
213+
```json
214+
{
215+
"distConfig": {
216+
"uglify": true
217+
},
218+
"libConfig": {
219+
"uglify": false
220+
}
221+
}
222+
```
223+
224+
## Contributing
225+
226+
We welcome your own contributions, ranging from code refactoring, documentation improvements, new feature implementations, bugs/issues reporting, etc. we recommend you follow the steps below to actively contribute to this project
227+
228+
1. Decide on what to help us with
229+
230+
2. Fork this repo to your machine
231+
232+
3. Implement your ideas, and once stable
233+
234+
4. Create a pull request, explaining your improvements/features
235+
236+
All future contributors will be included below and immensely appreciated. We look forward to your contributions.
237+
238+
## About Project Maintainers
239+
240+
This project is maintained by [harrison ifeanyichukwu](mailto:harrisonifeanyichukwu@gmail.com), a young, passionate full stack web developer, an [MDN](https://developer.mozilla.org/en-US/profiles/harrison-feanyichukwu) documentator, maintainer of node.js [xml-serializer](https://www.npmjs.com/package/@harrison-ifeanyichukwu/xml-serializer) [R-Server](https://github.com/harrison-ifeanyichukwu/r-server) and other great projects.
191241

192-
The config above uglifies `lib` builds but not `dist` builds.
242+
He is available for hire, ready to work on `PHP` projects, `Node.js` projects, `React` and `Angular` projects and stuffs like that. Looks forward to hearing from you soon!!!

0 commit comments

Comments
 (0)