1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
# Bower {#sec-bower}
[Bower](https://bower.io) is a package manager for web site front-end components. Bower packages (comprising of build artifacts and sometimes sources) are stored in `git` repositories, typically on Github. The package registry is run by the Bower team with package metadata coming from the `bower.json` file within each package.
The end result of running Bower is a `bower_components` directory which can be included in the web app's build process.
Bower can be run interactively, by installing `nodePackages.bower`. More interestingly, the Bower components can be declared in a Nix derivation, with the help of `bower2nix`.
## bower2nix usage {#ssec-bower2nix-usage}
Suppose you have a `bower.json` with the following contents:
### Example bower.json {#ex-bowerJson}
```json
"name": "my-web-app",
"dependencies": {
"angular": "~1.5.0",
"bootstrap": "~3.3.6"
}
```
Running `bower2nix` will produce something like the following output:
```nix
{ fetchbower, buildEnv }:
buildEnv {
name = "bower-env";
ignoreCollisions = true;
paths = [
(fetchbower "angular" "1.5.3" "~1.5.0" "1749xb0firxdra4rzadm4q9x90v6pzkbd7xmcyjk6qfza09ykk9y")
(fetchbower "bootstrap" "3.3.6" "~3.3.6" "1vvqlpbfcy0k5pncfjaiskj3y6scwifxygfqnw393sjfxiviwmbv")
(fetchbower "jquery" "2.2.2" "1.9.1 - 2" "10sp5h98sqwk90y4k6hbdviwqzvzwqf47r3r51pakch5ii2y7js1")
];
}
```
Using the `bower2nix` command line arguments, the output can be redirected to a file. A name like `bower-packages.nix` would be fine.
The resulting derivation is a union of all the downloaded Bower packages (and their dependencies). To use it, they still need to be linked together by Bower, which is where `buildBowerComponents` is useful.
## buildBowerComponents function {#ssec-build-bower-components}
The function is implemented in [pkgs/development/bower-modules/generic/default.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/bower-modules/generic/default.nix).
### Example buildBowerComponents {#ex-buildBowerComponents}
```nix
{
bowerComponents = buildBowerComponents {
name = "my-web-app";
generated = ./bower-packages.nix; # note 1
src = myWebApp; # note 2
};
}
```
In ["buildBowerComponents" example](#ex-buildBowerComponents) the following arguments are of special significance to the function:
1. `generated` specifies the file which was created by {command}`bower2nix`.
2. `src` is your project's sources. It needs to contain a {file}`bower.json` file.
`buildBowerComponents` will run Bower to link together the output of `bower2nix`, resulting in a `bower_components` directory which can be used.
Here is an example of a web frontend build process using `gulp`. You might use `grunt`, or anything else.
### Example build script (gulpfile.js) {#ex-bowerGulpFile}
```javascript
var gulp = require('gulp');
gulp.task('default', [], function () {
gulp.start('build');
});
gulp.task('build', [], function () {
console.log("Just a dummy gulp build");
gulp
.src(["./bower_components/**/*"])
.pipe(gulp.dest("./gulpdist/"));
});
```
### Example Full example — default.nix {#ex-buildBowerComponentsDefaultNix}
```nix
{
myWebApp ? {
outPath = ./.;
name = "myWebApp";
},
pkgs ? import <nixpkgs> { },
}:
pkgs.stdenv.mkDerivation {
name = "my-web-app-frontend";
src = myWebApp;
buildInputs = [ pkgs.nodePackages.gulp ];
bowerComponents = pkgs.buildBowerComponents {
# note 1
name = "my-web-app";
generated = ./bower-packages.nix;
src = myWebApp;
};
nativeBuildInputs = [
writableTmpDirAsHomeHook # note 3
];
buildPhase = ''
cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . # note 2
${pkgs.nodePackages.gulp}/bin/gulp build # note 4
'';
installPhase = "mv gulpdist $out";
}
```
A few notes about [Full example — `default.nix`](#ex-buildBowerComponentsDefaultNix):
1. The result of `buildBowerComponents` is an input to the frontend build.
2. Whether to symlink or copy the {file}`bower_components` directory depends on the build tool in use.
In this case a copy is used to avoid {command}`gulp` silliness with permissions.
3. {command}`gulp` requires `HOME` to refer to a writeable directory.
4. The actual build command in this example is {command}`gulp`. Other tools could be used instead.
## Troubleshooting {#ssec-bower2nix-troubleshooting}
### ENOCACHE errors from buildBowerComponents {#enocache-errors-from-buildbowercomponents}
This means that Bower was looking for a package version which doesn't exist in the generated `bower-packages.nix`.
If `bower.json` has been updated, then run `bower2nix` again.
It could also be a bug in `bower2nix` or `fetchbower`. If possible, try reformulating the version specification in `bower.json`.
|
