You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## [Setting Up Your Machine](aurelia-doc://section/1/version/1.0.0)
17
+
18
+
For this tutorial, we're going to use the Aurelia CLI. If you've already setup your machine with the CLI, you can skip to the next section. If not, then please install the following CLI prerequisites:
19
+
20
+
* Install NodeJS >= 4.x
21
+
* You can [download it here](https://nodejs.org/en/).
* Here's [a standard client](https://git-scm.com).
25
+
26
+
Once you have the prerequisites installed, you can install the Aurelia CLI itself. From the command line, use npm to install the CLI globally:
27
+
28
+
```
29
+
npm install aurelia-cli -g
30
+
```
31
+
32
+
> Info
33
+
> Always run commands from a Bash prompt. Depending on your environment, you may need to use `sudo` when executing npm global installs.
34
+
35
+
> Warning
36
+
> While creating a new project doesn't require NPM 3, front-end development, in general, requires a flat-package structure, which is not what NPM < 3 provides. It is recommended that you update to NPM 3, which will be able to manage this structural requirement. You can check your NPM version with `npm -v`. If you need to update, run `npm install npm -g`.
37
+
38
+
## [Creating A New Aurelia Project](aurelia-doc://section/2/version/1.0.0)
39
+
40
+
Now, that you've got your machine setup, we can create our contact manager app. To create the project, run `au new` from the command line. You will be presented with a number of options. Name the project "contact-manager" and then select either "Default ESNext" or "Default TypeScript" depending on what is most comfortable for you.
41
+
42
+
Once you've made your choice, the CLI will show you your selections and ask if you'd like to create the file structure. Hit enter to accpet the default "yes". After that, you'll be asked if you would like to install your new project's dependencies. Press enter to select the default "yes" for this as well.
43
+
44
+
Once the dependencies are installed (it will take a few minutes), your project is ready to go. Just change directory into the project folder and run it by typing `au run --watch`. This will run the app and watch the project's source for changes. Open a web browser and navigate to the url indicated in the CLI's output. If you've got everything setup correctly, you should see the message "Hello World!" in the browser.
For this tutorial, we're going to be working against a fake, in-memory backend. We've also pre-created the CSS, so we don't have to waste time on that here. Before we begin writing the app, you'll need to download these required assets and add them to your project.
*`name` - This is the name of the library as you will import it in your JavaScript or TypeScript code.
93
95
*`path` - This is a path to the single module file itself. This path is relative to your application's `src` folder. Also, you should not include the file extension. `.js` will be appended automatically.
94
96
95
97
If the `main` field of the library's `package.json` points to the single file that you need to bundle, then you can opt for a simplified configuration by just adding the package name to your dependencies directly:
96
98
97
-
```javascript
98
-
"dependencies": [
99
-
"library-name"
100
-
]
101
-
```
99
+
<code-listingheading="A Single File Module Dependency via Main">
100
+
<source-codelang="JavaScript">
101
+
"dependencies": [
102
+
"library-name"
103
+
]
104
+
</source-code>
105
+
</code-listing>
106
+
102
107
103
108
### A CommonJS Package
104
109
105
110
Many modules installed through NPM are packages made up of multiple source files. Configuring a library like this is a bit different than the single-file scenario above. Here's an example configuration for a multi-file package:
*`name` - This is the name of the library as you will import it in your JavaScript or TypeScript code.
119
127
*`path` - This is a path to the folder where the package's source is located. This path is relative to your application's `src` folder.
@@ -125,18 +133,20 @@ Many modules installed through NPM are packages made up of multiple source files
125
133
126
134
Libraries that predate module systems can be a pain because they often rely on global scripts which must be loaded before the library. These libraries also add their own global variables. An example of one such library is [bootstrap](http://getbootstrap.com/css/). Let's take a look at how to handle a legacy library like that.
*`name` - This is the name of the library as you will import it in your JavaScript or TypeScript code.
142
152
*`path` - This is a path to the folder where the package's source is located. This path is relative to your application's `src` folder.
@@ -150,21 +160,23 @@ Notice first that we've included "jquery" as one of our dependencies. We are abl
150
160
151
161
The Bootstrap example above results in the bundling of the JavaScript portions of the library. But, as you probably know, Bootstrap is mostly about CSS. The CSS files distributed with Bootstrap aren't traceable through the module system so this still doesn't result in the Bootstrap CSS being bundled. Here's how we solve that problem:
152
162
153
-
```javascript
154
-
"dependencies": [
155
-
"jquery",
156
-
{
157
-
"name":"bootstrap",
158
-
"path":"../node_modules/bootstrap/dist",
159
-
"main":"js/bootstrap.min",
160
-
"deps": ["jquery"],
161
-
"exports":"$",
162
-
"resources": [
163
-
"css/bootstrap.css"
163
+
<code-listingheading="A Library with Additional Resources">
164
+
<source-codelang="JavaScript">
165
+
"dependencies": [
166
+
"jquery",
167
+
{
168
+
"name": "bootstrap",
169
+
"path": "../node_modules/bootstrap/dist",
170
+
"main": "js/bootstrap.min",
171
+
"deps": ["jquery"],
172
+
"exports": "$",
173
+
"resources": [
174
+
"css/bootstrap.css"
175
+
]
176
+
}
164
177
]
165
-
}
166
-
]
167
-
```
178
+
</source-code>
179
+
</code-listing>
168
180
169
181
Notice that we've added a `resources` array. Here we can provide a list of additional files to be included with the bundle. These files are relative to the `path` designated above and must include the file extension. You can also use glob patterns in place of exact file names.
170
182
@@ -174,88 +186,95 @@ Notice that we've added a `resources` array. Here we can provide a list of addit
174
186
175
187
Sometimes you can't get a library to work with the module loading system. That's ok. You can still include it in the bundle, using traditional concatenation techniques. In fact, this is how the CLI bundles up the loader and promise polyfills. These items don't go into the `dependencies` section but instead go into the `prepend` section. This is because they aren't module dependencies. They also aren't relative to the `src`, but relative to the project folder. Using the `prepend` section causes the scripts to be prepended to the beginning of the bundle, using normal script concatenation techniques. Here's a full vendor bundle example, showing this and the rest of the techniques listed above.
## [Styling your Application](aurelia-doc://section/7/version/1.0.0)
243
257
244
258
There are many ways to style components in Aurelia. The CLI sets up your project to only process styles inside your application's `src` folder. Those styles can then be imported into a view using Aurelia's `require` element.
245
259
246
260
* If you aren't using any CSS preprocessor, you write css and then simply require it in the view like this:
247
-
```html
248
-
<requirefrom="./path/to/styles.css"></require>
249
-
```
261
+
262
+
<code-listingheading="Requiring styles.css">
263
+
<source-codelang="HTML">
264
+
<require from="./styles.css"></require>
265
+
</source-code>
266
+
</code-listing>
267
+
250
268
* For projects that use a CSS preprocessor (chosen from the cli setup questions):
251
269
* Write your styles in the format you chose (styl, sass, less ...).
252
270
* Require the style by `[filename].css` instead of `[filename].[extension]`. This is because
253
271
your style file is transpiled into a module that encodes the resulting `css` file extension.
254
-
```html
255
-
<!-- example -->
256
-
<!-- if you have stylus at: [project_root]/src/styles/main.styl -->
257
-
<requirefrom ="./styles/main.css"></require>
258
-
```
272
+
273
+
<code-listingheading="Requiring main.sass">
274
+
<source-codelang="HTML">
275
+
<require from ="./main.css"></require>
276
+
</source-code>
277
+
</code-listing>
259
278
260
279
Bear in mind that you can always configure things any way you want by modifying the tasks in the `aurelia_project/tasks` folder.
261
280
For styling purposes, you can modify the `process-css.js` file.
0 commit comments