{"id":13990882,"url":"https://github.com/w3tecch/aurelia-typescript-boilerplate","last_synced_at":"2025-04-12T11:44:44.547Z","repository":{"id":76888047,"uuid":"66075462","full_name":"w3tecch/aurelia-typescript-boilerplate","owner":"w3tecch","description":"A starter kit for building a standard navigation-style app with Aurelia, typescript and webpack by @w3tecch","archived":false,"fork":false,"pushed_at":"2018-07-15T12:24:01.000Z","size":1202,"stargazers_count":18,"open_issues_count":1,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-23T01:36:32.419Z","etag":null,"topics":["aurelia","aurelia-applications","aurelia-toolbox","boilerplate","bootstrap-4","cordova","cordova-application","e2e-tests","font-awesome","jasmine","jasmine-tests","jest-tests","karma-tests","nodejs","skeleton","starter-kit","typescript","wallaby","webpack","webpack-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/w3tecch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-19T10:44:35.000Z","updated_at":"2022-08-17T07:27:35.000Z","dependencies_parsed_at":"2023-03-01T08:00:17.920Z","dependency_job_id":null,"html_url":"https://github.com/w3tecch/aurelia-typescript-boilerplate","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3tecch%2Faurelia-typescript-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3tecch%2Faurelia-typescript-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3tecch%2Faurelia-typescript-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3tecch%2Faurelia-typescript-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/w3tecch","download_url":"https://codeload.github.com/w3tecch/aurelia-typescript-boilerplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248564223,"owners_count":21125406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aurelia","aurelia-applications","aurelia-toolbox","boilerplate","bootstrap-4","cordova","cordova-application","e2e-tests","font-awesome","jasmine","jasmine-tests","jest-tests","karma-tests","nodejs","skeleton","starter-kit","typescript","wallaby","webpack","webpack-server"],"created_at":"2024-08-09T13:03:27.260Z","updated_at":"2025-04-12T11:44:44.528Z","avatar_url":"https://github.com/w3tecch.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./w3tec-logo.png\" alt=\"w3tec\" width=\"400\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eAurelia Typescript Boilerplate\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://david-dm.org/w3tecch/aurelia-typescript-boilerplate\"\u003e\n    \u003cimg src=\"https://david-dm.org/w3tecch/aurelia-typescript-boilerplate/status.svg?style=flat\" alt=\"dependency\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://travis-ci.org/w3tecch/aurelia-typescript-boilerplate\"\u003e\n    \u003cimg src=\"https://travis-ci.org/w3tecch/aurelia-typescript-boilerplate.svg?branch=master\" alt=\"travis\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://ci.appveyor.com/project/dweber019/aurelia-typescript-boilerplate/branch/master\"\u003e\n    \u003cimg src=\"https://ci.appveyor.com/api/projects/status/7oyx5vxl6ue6oqsf/branch/master?svg=true\u0026passingText=Windows%20passing\u0026pendingText=Windows%20pending\u0026failingText=Windows%20failing\" alt=\"appveyor\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eA full configured and ready to go boilerplate/skeleton for an Aurelia app\u003c/b\u003e\u003c/br\u003e\n  Heavily inspired by \u003ca href=\"https://github.com/aurelia/skeleton-navigation/tree/master/skeleton-typescript-webpack\"\u003eAurelia Skeleton\u003c/a\u003e.\u003cbr\u003e\n  \u003csub\u003eMade with ❤️ by \u003ca href=\"https://github.com/w3tecch\"\u003ew3tech\u003c/a\u003e, \u003ca href=\"https://www.linkedin.com/in/david-weber-6a0819b7/\"\u003eDavid Weber\u003c/a\u003e and \u003ca href=\"https://github.com/w3tecch/template-gen/graphs/contributors\"\u003econtributors\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr /\u003e\n\n## ❯ Why\n\nThe skeletons provided by Aurelia are great but aren't ready for an enterprise grade app. This boilerplate provides a lot of features out of the box like i18n or an optin Cordova setup.\n\n## ❯ Table of Contents\n- [Getting Started](#-getting-started)\n- [Feature configuration](#-feature-configuration)\n- [Bundling](#-bundling)\n- [Running tests](#-running-tests)\n- [App configuration](#-app-configuration)\n- [HTML5 pushState routing](#-html5-pushstate-routing)\n- [Cordova - Mobile development](#-cordova-mobile-development)\n- [Docker](#-docker)\n- [Additional features](#-additional-features)\n\n\n## ❯ Getting started\n\nBefore you start, make sure you have a recent version of [NodeJS](http://nodejs.org/) environment *\u003e=6.0* with NPM 3 or Yarn.\n\nFrom the project folder, execute the following commands:\n\n```shell\nnpm install # or: yarn install\n```\n\nThis will install all required dependencies, including a local version of Webpack that is going to\nbuild and bundle the app. There is no need to install Webpack globally.\n\nTo run the app execute the following command:\n\n```shell\nnpm start # or: yarn start\n```\n\nThis command starts the webpack development server that serves the build bundles.\nYou can now browse the skeleton app at http://localhost:8080 (or the next available port, notice the output of the command). Changes in the code\nwill automatically build and reload the app.\n\n### Running with Hot Module Reload\n\nIf you wish to try out the experimental Hot Module Reload, you may run your application with the following command:\n\n```shell\nnpm start -- webpack.server.hmr\n```\n\n## ❯ Feature configuration\n\nMost of the configuration will happen in the `webpack.config.js` file.\nThere, you may configure advanced loader features or add direct SASS or LESS loading support.\n\n## ❯ Bundling\n\nTo build an optimized, minified production bundle (output to /dist) execute:\n\n```shell\nnpm start -- build\n```\n\nTo build\n\nTo test either the development or production build execute:\n\n```shell\nnpm start -- serve\n```\n\nThe production bundle includes all files that are required for deployment.\n\n## ❯ Running tests\n\nThis skeleton provides three frameworks for running tests.\n\nYou can choose one or two and remove the other, or even use all of them for different types of tests.\n\nBy default, both Jest and Karma are configured to run the same tests with Jest's matchers (see Jest documentation for more information).\n\nIf you wish to only run certain tests under one of the runners, wrap them in an `if`, like this:\n\n```js\nif (jest) {\n  // since only jest supports creating snapshot:\n  it('should render correctly', () =\u003e {\n    expect(document.body.outerHTML).toMatchSnapshot();\n  });\n}\n```\n\n### Jest + Jasmine 2\n\nJest is a powerful unit testing runner and framework.\nIt runs really fast, however the tests are run under NodeJS, not the browser.\nThis means there might be some cases where something you'd expect works in reality, but fails in a test. One of those things will be SVG, which isn't supported under NodeJS. However, the framework is perfect for doing unit tests of pure functions, and works pretty well in combination with `aurelia-testing`.\n\nTo create new Jest tests, create files with the extension `.spec.ts`, either in the `src` directory or in the `test/unit` directory.\n\nTo run the Jest unit tests, run:\n\n```shell\nnpm test\n```\n\nTo run the Jest watcher (re-runs tests on changes), run:\n\n```shell\nnpm start -- test.jest.watch\n```\n\n### Protractor (E2E / integration tests)\n\nIntegration tests can be performed with [Protractor](http://angular.github.io/protractor/#/).\n\n1. Place your E2E-Tests into the folder ```test/e2e``` and name them with the extension `.e2e.ts`.\n\n2. Run the tests by invoking\n\n```shell\nnpm start -- e2e\n```\n\n### Running all test suites\n\nTo run all the unit test suites and the E2E tests, you may simply run:\n\n```shell\nnpm start -- test.all\n```\n\n## ❯ App configuration\nThere is an app configuration management in place. Two standard environments are already set (development and production).\nYou can for example build the production with:\n\n```shell\nnpm start -- webpack.build.production\n```\n\nIf you like to add an additional configuration you have to do the following two steps:\n1. Add the configuration json to ```app/config```, example preprod.json\n2. Add the corresponding command to ```package-script.js``` and pass the right argument like ```--env.config=preprod```\n\nExample for path ```webpack.build.preprod```:\n```javascript\npreprod: {\n  inlineCss: series(\n    'nps webpack.build.before',\n    'webpack --progress -p --env.production --env.config=preprod'\n  ),\n  default: series(\n    'nps webpack.build.before',\n    'webpack --progress -p --env.production --env.extractCss --env.config=preprod'\n  ),\n  serve: series.nps(\n    'webpack.build.production',\n    'serve'\n  ),\n}\n```\n\n## ❯ HTML5 pushState routing\nBy default pushState, also known as html5 routing, is enabled. The Webpack server is already configured to handle this but many webserver need\nextra configuration to enable this.\n\n## ❯ Cordova - Mobile development\n\n### Installation\nInitiate cordova with the following commands:\n```shell\nnpm install -g cordova\nnpm start -- mobile.setup\n```\n\n### Run and build\nCordova takes the ```www``` folder source to create the Cordova app. This ```www``` folder is a symlink pointing to the ```dist``` folder.\nSo make sure you run for example ```npm start -- build``` first before running/building a Cordova app.\n\nSometimes the ```www``` symlink is removed (e.g. git clone). Run this command to fix this:\n```shell\nnpm start -- mobile.link\n```\n\n## ❯ Docker\nThere is a ```Dockerfile``` using the [nginx](https://hub.docker.com/_/nginx/) image to build the docker image.\n\n### Getting started\nFirst build your aurelia app with\n```shell\nnpm start build\n```\n\nThen build the image with\n```shell\ndocker build -t nginx-aurelia .\n```\n\nThen run a container with\n```shell\ndocker run --name aurelia-app -d -p 8080:80 nginx-aurelia\n```\nNow your website is available with ```http://localhost:8080```.\n\nIf you like to update the source do this\n```shell\ndocker cp ./dist/. mycontainer:/usr/share/nginx/html\n```\n\n## ❯ Additional features\nThis repository houses some additional features which prove to be very useful in projects.\n\n### String polyfill\nThe file `utils/polyfills.utils.ts` contains a string polyfills.\nWith this polyfill you can do this:\n```\nString.isEmpty('Teststring') =\u003e false\nString.isEmpty('') =\u003e true\nString.isEmpty(undefined) =\u003e true\n```\n\n### Validation\nThe file `utils/validation.utils.ts` contains some validation helper functions and regex patterns.\n\nThe function `validateFilledFieldsWithValidationRules` us really useful as you can check a object which is already prefilled if it's valid and if not show errors.\n\nThe function `controllerValidByRules` will check if a validation controller is valid.\n\nThis could be an example implementation\n```\nclass FormExample {\n\n  @bindable({ defaultBindingMode: bindingMode.twoWay }) public user: User;\n\n  private controller: ValidationController;\n  private rules: Rule\u003cCustomerContactRestModel, any\u003e[][];\n\n  public constructor(\n    private validationControllerFactory: ValidationControllerFactory\n  ) {\n    this.controller = this.validationControllerFactory.createForCurrentScope();\n    this.controller.validateTrigger = validateTrigger.changeOrBlur;\n  }\n\n  public bind(): void {\n    this.setupValidationRules();\n    validateFilledFieldsWithValidationRules(this.rules, this.user, this.controller);\n  }\n\n  @computedFrom('user')\n  public get isValid(): boolean {\n    return controllerValidByRules(this.rules, this.user, this.controller);\n  }\n\n  private setupValidationRules(): void {\n    this.rules = ValidationRules\n      .ensure((user: User) =\u003e user.lastName)\n        .displayName('USER.LAST_NAME')\n        .required()\n      .ensure((user: User) =\u003e user.email)\n        .displayName('USER.EMAIL')\n        .email()\n      .on(this.user).rules;\n  }\n}\n```\n\n### i18n integration\nYou can pass a translation string into the `displayName('USER.LAST_NAME')` and it will be translated for you.\n\nAdditionally you can translate methods like `.required()` in `src/local/*` as demonstrated in the files.\n\nIf you use the the method `withMessageKey('YOUR.TRANSLATION')` you can pass a translation string and it will be translated for you.\n\n### Route generator service\nIf you have router tree like this\n```\n     root\n    /    \\\nleft      right\n```\nYou can't navigate from `left` to `right` with `this.router.navigateToRoute(...)` as `right` is in a branch which `left` is unaware of. This is due to the injection of the router service.\n\nOne solution is to use `this.router.navigate(...)` but this is unsafe as if the route configuration is changed the navigation is broken as it's hard coded.\n\nThe `route-generator.service.ts` will provide a type safe solution for save navigation.\n\nCheck the following files to get an idea how to use it:\n- `route-generator.service.ts`\n- `app.vm.ts` and `app.routes.ts`\n- `child-router.vm.ts` and `child-router.routes.ts`\n\nAs an example you could navigate like this from `left` to `right`\n```\nthis.routeGeneratorService.navigateByRouteNames(\n  { routeName: 'root' },\n  { routeName: 'right' }\n);\n```\n\nYou can also pass route parameters like this but remember that query parameter have to attached to the last element\n```\nthis.routeGeneratorService.navigateByRouteNames(\n  { routeName: 'root', params: { id: '1' }},\n  { routeName: 'right' }\n);\n```\n\n### Class transformer (model handling)\nWe have included the [class transformer](https://github.com/typestack/class-transformer) which helps creating models (`src/app/models/*`). This transformation can be done\nin both direction (rest to model, model to rest).\n\n### Dialog service\nThere is a custom dialog implementation for simpler usage of elements in dialogs.\n\nThe Service is named `generic-dialog.service.ts` and an example can be found in `welcome.vm.ts`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3tecch%2Faurelia-typescript-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fw3tecch%2Faurelia-typescript-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3tecch%2Faurelia-typescript-boilerplate/lists"}