Merge pull request #959 from marmelab/webpack_v2

[RFR] Better integration with module bundlers
marmelab · Sep 7, 2016 · 5f317b5 · 5f317b5
2 parents 1dc0cac + 6a6ee93
commit 5f317b5
Show file tree

Hide file tree

Showing 20 changed files with 165 additions and 296 deletions.
diff --git a/.babelrc b/.babelrc
@@ -0,0 +1,4 @@
+{
+    "presets": ["es2015", "stage-2"],
+    "plugins": ["add-module-exports"]
+}
diff --git a/.gitignore b/.gitignore
@@ -1,12 +1,14 @@
-node_modules
-dist
-.tmp
 .sass-cache
+.tmp
+build/
+dist
+examples/blog/assets
+examples/blog/build
+lib/
+node_modules
+npm-debug.log
+src/css
 src/javascripts/bower_components
 src/javascripts/config.js
 src/javascripts/test/fixtures/examples/blog
 src/styles/*.css
-src/css
-examples/blog/build
-examples/blog/assets
-npm-debug.log
diff --git a/Makefile b/Makefile
@@ -7,13 +7,21 @@ install:
 run: examples/blog/build
 	@cp node_modules/fakerest/dist/FakeRest.min.js examples/blog/build/fakerest.js
 	@cp node_modules/sinon/pkg/sinon-server-1.14.1.js examples/blog/build/sinon-server.js
-	@./node_modules/webpack-dev-server/bin/webpack-dev-server.js --colors --devtool cheap-module-inline-source-map --content-base examples/blog --port 8000
+	@./node_modules/webpack-dev-server/bin/webpack-dev-server.js --colors --inline --hot --devtool cheap-module-inline-source-map --content-base examples/blog --port 8000
 
 examples/blog/build:
 	@mkdir examples/blog/build
 
+transpile:
+	@mkdir -p lib/
+	@rm -rf lib/*
+	@./node_modules/.bin/babel src/javascripts -d lib/javascripts --source-maps > /dev/null
+	@cd src && cp --parents `find . -name *.html` ../lib # copy all HTML files keeping structure from src to lib
+	@cp -Rf ./src/sass/ lib/
+
 build:
-	@NODE_ENV=production ./node_modules/webpack/bin/webpack.js -p --optimize-minimize --optimize-occurence-order --optimize-dedupe --progress --devtool source-map
+	@make transpile
+	@NODE_ENV=production ./node_modules/webpack/bin/webpack.js -p --optimize-minimize --optimize-occurence-order --optimize-dedupe --progress --devtool --source-map
 	@cp -Rf build examples/blog/
 	@echo "Files build/ng-admin.min.css and build/ng-admin.min.js updated (with minification)"
 

diff --git a/README.md b/README.md
@@ -22,9 +22,61 @@ npm install ng-admin --save
 bower install ng-admin --save
 ```
 
-Add the `ng-admin.min.css` and `ng-admin.min.js` to the HTML, add a `<div ui-view>`, and configure the admin:
+### With a Module Bundler
 
-```html
+`ng-admin` is fully compatible with Webpack, and should also be compatible with all
+available major module bundlers. If you use one of them, you just have to add this line:
+
+``` js
+const myApp = angular.module('myApp', [
+    require('ng-admin'),
+    // ...
+]);
+```
+
+**Important note:** as we include HTML templates using `require` to prevent the AJAX
+request implied by `templateUrl`, you will need to configure your module bundler
+to deal with HTML. It can be accomplished with Webpack using the HTML loader:
+
+``` js
+module.exports = {
+    // ...
+    module: {
+        loaders: [
+            // ...
+            { test: /\.html$/, loader: 'html' },
+        ]
+    },
+};
+```
+
+If your module bundler also supports SASS or CSS, you can also include stylesheets using:
+
+``` js
+// SASS version
+require('ng-admin/lib/sass/ng-admin.scss');
+
+// CSS version
+require('ng-admin/build/ng-admin.min.css');
+```
+
+Using a module bundler, you would also be able to generate the source map for all your JavaScript
+and stylesheets, helping you to hunt even the most obscure bugs.
+
+### Without a Module Bundler
+
+If you don't have a module bundler, don't worry: you can still include `ng-admin` with a `<script>` tag:
+
+``` html
+<link rel="stylesheet" href="node_modules/ng-admin/build/ng-admin.min.css">
+<script src="node_modules/ng-admin/build/ng-admin.min.js"></script>
+```
+
+## Bootstraping your Admin
+
+Just add a `<div ui-view>` into your HTML, add a `ng-app` attribute on your `body`, and configure the admin:
+
+``` html
 <!doctype html>
 <html lang="en">
   <head>

diff --git a/UPGRADE-1.0.md b/UPGRADE-1.0.md
@@ -39,3 +39,28 @@ After editing an entity, ng-admin now redirects to the previous page (e.g. list
 Similarly, after creating an entity, ng-admin now redirects to the show view if it's enabled, or to the list view if it's not.
 
 If you want to reverse to the pre-1.0 behavior, override `CreationView.onSubmitSuccess()` and `EditionView.onSubmitSuccess()` (cf [doc/reference/View](doc/reference/View.md)).
+
+## Better Integration with Module Bundlers
+
+We reviewed the way we publish ng-admin in order to ease integration with module bundlers. You can now just require `ng-admin` dependency directly into your JavaScript file:
+
+``` js
+const myApp = angular.module('myApp', [
+    require('ng-admin'),
+    // ...
+]);
+```
+
+Furthermore, if your module bundler supports CSS and/or SASS, you can also embed styles using:
+
+``` js
+// SASS version
+require('ng-admin/lib/sass/ng-admin.scss');
+
+// CSS version
+require('ng-admin/build/ng-admin.min.css');
+```
+
+## Removing `ng-admin-only` build
+
+We used to build two versions of `ng-admin`: a standalone one and a `only` one. The latter includes only files required to ng-admin. But it was a little buggy and required a lot of dependencies. Including a functional version of this '-only' version was so painful that we decided to abandon it in profit of a better bundler integration (see previous paragraph).
diff --git a/build/ng-admin-only.min.css b/build/ng-admin-only.min.css
diff --git a/build/ng-admin-only.min.css.map b/build/ng-admin-only.min.css.map
diff --git a/build/ng-admin-only.min.js b/build/ng-admin-only.min.js
diff --git a/build/ng-admin-only.min.js.map b/build/ng-admin-only.min.js.map
diff --git a/build/ng-admin.min.css b/build/ng-admin.min.css
diff --git a/build/ng-admin.min.css.map b/build/ng-admin.min.css.map
diff --git a/build/ng-admin.min.js b/build/ng-admin.min.js
diff --git a/build/ng-admin.min.js.map b/build/ng-admin.min.js.map
diff --git a/doc/Production.md b/doc/Production.md
@@ -1,52 +1,6 @@
 # Getting Ready For Production
 
-Before deploying your ng-admin backend to production, there are a few things to know.
-
-## Bundling only the dependencies you need
-
-All the examples in the ng-admin documentation include the minified JS and CSS:
-
-```html
-<link rel="stylesheet" href="/path/to/node_modules/ng-admin/build/ng-admin.min.css">
-<script src="/path/to/node_modules/ng-admin/build/ng-admin.min.js"></script>
-```
-
-These two files contain the ng-admin source, *as well as the source of all dependencies, including angular.js*, all combined and minified into a single file. This may not be what you want in production.
-
-If your admin page has more dependencies, or if you have a custom build utility (we advise using [webpack](http://webpack.github.io/)), you'll need to include the ng-admin standalone version (`build/ng-admin-only.min.js`), as well as all the other dependencies.
-
-Here is a snippet showing all required scripts:
-
-``` html
-<link rel="stylesheet" href="node_modules/bootstrap/css/bootstrap.min.css" />
-<link rel="stylesheet" href="node_modules/ng-admin/build/ng-admin-only.min.css" />
-
-<script src="node_modules/angular/angular.js"></script>
-<script src="node_modules/angular-ui-bootstrap/dist/ui-bootstrap-tpls.js"></script>
-<script src="node_modules/angular-resource/angular-resource.min.js"></script>
-<script src="node_modules/angular-sanitize/angular-sanitize.min.js"></script>
-<script src="node_modules/angular-ui-codemirror/ui-codemirror.min.js"></script>
-<script src="node_modules/angular-ui-router/release/angular-ui-router.min.js"></script>
-<script src="node_modules/angular-numeraljs/dist/angular-numeraljs.min.js"></script>
-<script src="node_modules/humane/humane.js"></script>
-<script src="node_modules/inflection/inflection.min.js"></script>
-<script src="node_modules/underscore/underscore-min.js"></script>
-<script src="node_modules/ng-file-upload/ng-file-upload-all.min.js"></script>
-<script src="node_modules/ngInflection/ngInflection.js"></script>
-<script src="node_modules/nprogress/nprogress.js"></script>
-<script src="node_modules/restangular/dist/restangular.min.js"></script>
-<script src="node_modules/textAngular/dist/textAngular.min.js"></script>
-<script src="node_modules/papaparse/papaparse.min.js"></script>
-<script src="node_modules/numeral/min/numeral.min.js"></script>
-<script src="node_modules/codemirror/lib/codemirror.js"></script>
-<script src="node_modules/codemirror/addon/edit/closebrackets.js"></script>
-<script src="node_modules/codemirror/addon/lint/lint.js"></script>
-<script src="node_modules/jsonlint/lib/jsonlint.js"></script>
-<script src="node_modules/codemirror/addon/lint/json-lint.js"></script>
-<script src="node_modules/codemirror/addon/selection/active-line.js"></script>
-<script src="node_modules/codemirror/mode/javascript/javascript.js"></script>
-<script src="node_modules/ng-admin/build/ng-admin-only.min.js"></script>
-```
+Before deploying your ng-admin backend to production, there are a few tricks to know:
 
 ## Performance Boosters
 

diff --git a/package.json b/package.json
@@ -3,14 +3,21 @@
   "version": "1.0.0-alpha4",
   "license": "MIT",
   "private": false,
-  "main": "build/ng-admin.min.js",
+  "main": "lib/javascripts/ng-admin.js",
   "repository": {
     "type": "git",
     "url": "git://github.com/marmelab/ng-admin.git"
   },
+  "files": [
+      "*.md",
+      "build/",
+      "lib/"
+  ],
+  "dependencies": {
+    "angular": "~1.4.8"
+  },
   "devDependencies": {
-    "admin-config": "^0.11.0",
-    "angular": "~1.4.8",
+    "admin-config": "0.12.1",
     "angular-mocks": "~1.4.8",
     "angular-numeraljs": "^1.1.6",
     "angular-sanitize": "^1.3.15",
@@ -19,9 +26,13 @@
     "angular-ui-codemirror": "^0.3.0",
     "angular-ui-router": "^0.2.14",
     "angularjs": "0.0.1",
-    "babel": "^4.6.0",
-    "babel-core": "^5.2.17",
-    "babel-loader": "^5.0.0",
+    "babel": "^6.5.2",
+    "babel-cli": "^6.14.0",
+    "babel-core": "^6.14.0",
+    "babel-loader": "^6.2.5",
+    "babel-plugin-add-module-exports": "^0.2.1",
+    "babel-preset-es2015": "^6.14.0",
+    "babel-preset-stage-2": "^6.13.0",
     "bootstrap-sass": "^3.3.4",
     "chai": "^3.3.0",
     "codemirror": "^5.2.0",
@@ -49,7 +60,6 @@
     "karma-webpack": "~1.7.0",
     "mocha": "^2.1.0",
     "ng-annotate-loader": "0.0.2",
-    "ng-annotate-webpack-plugin": "^0.1.2",
     "ng-file-upload": "^7.0.12",
     "nginflection": "^1.1.10",
     "ngtemplate-loader": "^1.3.0",
@@ -77,6 +87,7 @@
     "node": ">=4.2.0"
   },
   "scripts": {
+    "prepublish": "make build",
     "test": "make test"
   }
 }
diff --git a/src/javascripts/ng-admin.js b/src/javascripts/ng-admin.js
@@ -1,18 +1,28 @@
 require('es6-promise').polyfill(); // for IE
 
+require('./vendors');
 require('./ng-admin/Main/MainModule');
 require('./ng-admin/Crud/CrudModule');
 
 import Factory from 'admin-config/lib/Factory';
 
-var factory = angular.module('AdminDescriptionModule', []);
+const moduleName = 'ng-admin';
+const factory = angular.module('AdminDescriptionModule', []);
 factory.constant('AdminDescription', new Factory());
 
-var ngadmin = angular.module('ng-admin', ['ui.select', 'main', 'crud', 'AdminDescriptionModule']);
-ngadmin.config(function(NgAdminConfigurationProvider, AdminDescription) {
+const ngadmin = angular.module(moduleName, [
+    'ui.select',
+    'main',
+    'crud',
+    'AdminDescriptionModule'
+]);
+
+ngadmin.config(['NgAdminConfigurationProvider', 'AdminDescription', function(NgAdminConfigurationProvider, AdminDescription) {
     NgAdminConfigurationProvider.setAdminDescription(AdminDescription);
-});
+}]);
 
-ngadmin.config(function(uiSelectConfig) {
+ngadmin.config(['uiSelectConfig', function(uiSelectConfig) {
     uiSelectConfig.theme = 'bootstrap';
-});
+}]);
+
+export default moduleName;