summary refs log tree commit diff
path: root/doc/languages-frameworks/bower.xml
blob: 118f6e10473ab855aa7cb09b9d9bd8d004cf9811 (plain) (blame)
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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
<section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="sec-bower">
 <title>Bower</title>

 <para>
  <link xlink:href="http://bower.io">Bower</link> is a package manager for web
  site front-end components. Bower packages (comprising of build artefacts and
  sometimes sources) are stored in <command>git</command> repositories,
  typically on Github. The package registry is run by the Bower team with
  package metadata coming from the <filename>bower.json</filename> file within
  each package.
 </para>

 <para>
  The end result of running Bower is a <filename>bower_components</filename>
  directory which can be included in the web app's build process.
 </para>

 <para>
  Bower can be run interactively, by installing
  <varname>nodePackages.bower</varname>. More interestingly, the Bower
  components can be declared in a Nix derivation, with the help of
  <varname>nodePackages.bower2nix</varname>.
 </para>

 <section xml:id="ssec-bower2nix-usage">
  <title><command>bower2nix</command> usage</title>

  <para>
   Suppose you have a <filename>bower.json</filename> with the following
   contents:
   <example xml:id="ex-bowerJson">
    <title><filename>bower.json</filename></title>
<programlisting language="json">
<![CDATA[{
  "name": "my-web-app",
  "dependencies": {
    "angular": "~1.5.0",
    "bootstrap": "~3.3.6"
  }
}]]>
</programlisting>
   </example>
  </para>

  <para>
   Running <command>bower2nix</command> will produce something like the
   following output:
<programlisting language="nix">
<![CDATA[{ 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")
]; }]]>
</programlisting>
  </para>

  <para>
   Using the <command>bower2nix</command> command line arguments, the output
   can be redirected to a file. A name like
   <filename>bower-packages.nix</filename> would be fine.
  </para>

  <para>
   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 <varname>buildBowerComponents</varname> is useful.
  </para>
 </section>

 <section xml:id="ssec-build-bower-components">
  <title><varname>buildBowerComponents</varname> function</title>

  <para>
   The function is implemented in
   <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/bower-modules/generic/default.nix">
   <filename>pkgs/development/bower-modules/generic/default.nix</filename></link>.
   Example usage:
   <example xml:id="ex-buildBowerComponents">
    <title>buildBowerComponents</title>
<programlisting language="nix">
bowerComponents = buildBowerComponents {
  name = "my-web-app";
  generated = ./bower-packages.nix; <co xml:id="ex-buildBowerComponents-1" />
  src = myWebApp; <co xml:id="ex-buildBowerComponents-2" />
};
</programlisting>
   </example>
  </para>

  <para>
   In <xref linkend="ex-buildBowerComponents" />, the following arguments are
   of special significance to the function:
   <calloutlist>
    <callout arearefs="ex-buildBowerComponents-1">
     <para>
      <varname>generated</varname> specifies the file which was created by
      <command>bower2nix</command>.
     </para>
    </callout>
    <callout arearefs="ex-buildBowerComponents-2">
     <para>
      <varname>src</varname> is your project's sources. It needs to contain a
      <filename>bower.json</filename> file.
     </para>
    </callout>
   </calloutlist>
  </para>

  <para>
   <varname>buildBowerComponents</varname> will run Bower to link together the
   output of <command>bower2nix</command>, resulting in a
   <filename>bower_components</filename> directory which can be used.
  </para>

  <para>
   Here is an example of a web frontend build process using
   <command>gulp</command>. You might use <command>grunt</command>, or anything
   else.
  </para>

  <example xml:id="ex-bowerGulpFile">
   <title>Example build script (<filename>gulpfile.js</filename>)</title>
<programlisting language="javascript">
<![CDATA[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/"));
});]]>
</programlisting>
  </example>

  <example xml:id="ex-buildBowerComponentsDefaultNix">
   <title>Full example — <filename>default.nix</filename></title>
<programlisting language="nix">
{ myWebApp ? { outPath = ./.; name = "myWebApp"; }
, pkgs ? import &lt;nixpkgs&gt; {}
}:

pkgs.stdenv.mkDerivation {
  name = "my-web-app-frontend";
  src = myWebApp;

  buildInputs = [ pkgs.nodePackages.gulp ];

  bowerComponents = pkgs.buildBowerComponents { <co xml:id="ex-buildBowerComponentsDefault-1" />
    name = "my-web-app";
    generated = ./bower-packages.nix;
    src = myWebApp;
  };

  buildPhase = ''
    cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . <co xml:id="ex-buildBowerComponentsDefault-2" />
    export HOME=$PWD <co xml:id="ex-buildBowerComponentsDefault-3" />
    ${pkgs.nodePackages.gulp}/bin/gulp build <co xml:id="ex-buildBowerComponentsDefault-4" />
  '';

  installPhase = "mv gulpdist $out";
}
</programlisting>
  </example>

  <para>
   A few notes about <xref linkend="ex-buildBowerComponentsDefaultNix" />:
   <calloutlist>
    <callout arearefs="ex-buildBowerComponentsDefault-1">
     <para>
      The result of <varname>buildBowerComponents</varname> is an input to the
      frontend build.
     </para>
    </callout>
    <callout arearefs="ex-buildBowerComponentsDefault-2">
     <para>
      Whether to symlink or copy the <filename>bower_components</filename>
      directory depends on the build tool in use. In this case a copy is used
      to avoid <command>gulp</command> silliness with permissions.
     </para>
    </callout>
    <callout arearefs="ex-buildBowerComponentsDefault-3">
     <para>
      <command>gulp</command> requires <varname>HOME</varname> to refer to a
      writeable directory.
     </para>
    </callout>
    <callout arearefs="ex-buildBowerComponentsDefault-4">
     <para>
      The actual build command. Other tools could be used.
     </para>
    </callout>
   </calloutlist>
  </para>
 </section>

 <section xml:id="ssec-bower2nix-troubleshooting">
  <title>Troubleshooting</title>

  <variablelist>
   <varlistentry>
    <term>
     <literal>ENOCACHE</literal> errors from <varname>buildBowerComponents</varname>
    </term>
    <listitem>
     <para>
      This means that Bower was looking for a package version which doesn't
      exist in the generated <filename>bower-packages.nix</filename>.
     </para>
     <para>
      If <filename>bower.json</filename> has been updated, then run
      <command>bower2nix</command> again.
     </para>
     <para>
      It could also be a bug in <command>bower2nix</command> or
      <command>fetchbower</command>. If possible, try reformulating the version
      specification in <filename>bower.json</filename>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </section>
</section>