search

aurelia / cli

The Aurelia 1 command line tool. Use the CLI to create projects, scaffold components, and bundle your app for release.
MIT License
407 stars 133 forks source link

[Docs] Document CLI Recipes #393

Open AStoker opened 7 years ago

AStoker commented 7 years ago

Recipes Documentation

Many of the issues that arise for the CLI project are actually questions about implementation disguised as bugs. To help with this, a proposed "Recipes" section is being created.
"Recipes" are quick examples of how to accomplish a specific task, with code examples included. For example, a recipe might contain how to configure the CLI to use Electron, or how to get the tests to run off of source code instead of the bundled code.

Use this issue to discuss what kinds of recipes should be added, and which ones will be most helpful.

Note: Some of the suggestions may be combined, broken out, or moved to a different location (and some of them are features not yet implemented). This is just an initial location to gather ideas.

Recipes to add

Thanood commented 7 years ago

A few first recipes:

Enable BrowserSync to proxy a backend server

In aurelia_project/tasks/run.js change the server task to:

let serve = gulp.series(
  build,
  done => {
    browserSync({
      // online: false,
      // notify: true,
      open: false,
      port: 9000,
      logLevel: 'silent',
      proxy: {
        target: 'localhost:24562'
      }
    }, function(err, bs) {
      let urls = bs.options.get('urls').toJS();
      console.log(`Application Available At: ${urls.local}`);
      console.log(`BrowserSync Available At: ${urls.ui}`);
      done();
    });
  }
);

Replace localhost:24562 to the url you'd like to proxy.

Enable requirejs loading from 'scripts' directory

IMO, this should work but doesn't, see #387

Add this to build.loader in aurelia.json:

"config": {
  "baseUrl": "scripts/"
},
adriatic commented 7 years ago

@AStoker allow me to register my big interest in participating in this discussion. @Thanood and I represent the same group (Aurelia-Tools / Aurelia-UI-Toolkits) and from all of our projects, it is Monterey that is best suited to disseminate the information we hope to collect here.

Reference to Monterey (https://github.com/monterey-framework/monterey) allows me to mention a lot more ambitious tasks we plan to discuss with you (on recommendation from @EisenbergEffect who is well aware of Monterey's future plans and role in Aurelia community). I will stop by just this introduction as I do not want to disrupt the process already taking place in this article.

cc: @JeroenVinke

CasiOo commented 7 years ago

I have done all of the above, and are using it in all my projects. Would love to show how all of it is done, but I'm not a good writer.

On a site note: I would like a way for au generate element to accept a path to place the generated element in, but it always seem to end up in resources/elements :(

Thanood commented 7 years ago

Adding plugins such as materializecss. Includes setting up sass tasks to override materializecss defaults. Would be nice with complete configuration guides.

Having created a Materialize bridge, I find this very interesting.. 😃

With JSPM one would use an override. While I guess this is possible in aurelia.json, I'd really like to see a working example of it including processing sass changes. 😃

Btw. here's the Materialize config (as a separate bundle):

{
  "name": "materialize-bundle.js",
  "dependencies": [
    "jquery",
    {
      "name": "materialize-css",
      "path": "../node_modules/materialize-css/dist",
      "main": "js/materialize.amd",
      "deps": [
        "jquery"
      ],
      "resources": [
        "css/materialize.css"
      ],
      "exports": "Materialize"
    }
  ]
}

There are some more tasks needed to prepare an AMD compatible version. I don't want to spam too much info right now but the process is described in this GitBook (see package.json scripts section, especially the materialize task).

AStoker commented 7 years ago

Love the feedback! Once we start getting a good list of recipes (already have a good start), we'll start discussing each one to get the proper setup.

martonsagi commented 7 years ago

This is interesting! Yesterday, I was just thinking on how to make aurelia.json setup easier - especially on setting up bundle.dependencies correctly.

There are lots of blog posts, SO answers covering specific libraries, etc.., which is great. But that's fragmented information, so finding all the relevant bits can be confusing and time consuming procedure.

If we could collect well-tested, working library configurations or recipes to one central place (e.g. aurelia/registry repo), it would be possible to create an automatized mechanism for aurelia.json configuration. The whole thing could be based on bundle recipes provided by other community members and plugin devs. I mean, plugin creators usually place setup information in their readme, therefore it wouldn't be hard to copy that metadata into a central location too, e.g. as part of the publishing step. Regarding external libraries, of course, it would involve some community effort to collect all those info. :)

I've created a proof-of-concept tool to experiment with that idea: aurelia-cli-pacman. Basically, it's just a cli task + a little nodejs lib. Beyond npm installation, it can modify aurelia.json as well - if a predefined metadata file is available in a designated location (e.g. ./registry sub-folder).

Is this something that might worth thinking about? What are your opinions?

AStoker commented 7 years ago

@martonsagi, nice tool you got there! I think Eisenberg was going to implement that kind of functionality directly into the CLI soon.

adriatic commented 7 years ago

@AStoker @martonsagi @JeroenVinke Gentlemen allow me to "barge in" without invitation as this discussion is very relevant for our Monterey project which @EisenbergEffect introduced his month in his blog. I am referencing Rob to indicate that he is involved with Monterey's design and future evolution in the intersection of Monterey and aurelia-cli tool.

So to ensure that we keep all this information and future plans discussions together, I propose that we continue this specific discussion that @martonsagi just initiated in this issue - as it is a lot more than just a "docs" issue.

AStoker commented 7 years ago

@adriatic, I think that having a discussion over on Monterey would be helpful. However having a separate discussion here, keeping recipes as the main focus I think is still important. Not everyone will be using Monterey, and recipes should be agnostic of your IDE. This issue is not to discuss development of the CLI. It is to just get some ideas on what kind of recipes we'd like to have documented, similar to how Gulp has a recipes section.
I appreciate what you guys are doing on Monterey! But I think it's important to keep separate CLI recipes from Monterey (in as far as repo locations).

adriatic commented 7 years ago

@AStoker it seems you you took my intent as trying to hijack this discussion, while I actually proposed a fork:

I propose that we continue this specific discussion that @martonsagi just initiated in this issue

Obviously my fault is that I did not make my intent more clear, so I apologize for being clumsy 😏

AStoker commented 7 years ago

Not a problem @adriatic! Sorry for misunderstanding you there. The medium of the internet is not the best to convey intentions (or understand them) 😉
Thanks for clarifying! I think having that "fork" discussion would be a great idea to improve the Monterey tool!

martonsagi commented 7 years ago

@adriatic Thanks for your interest, I would be glad to contribute to the Monterey project.

@AStoker Thanks for your feedback. I wasn't entirely sure that this issue would be the best place to discuss my idea, but it seemed relevant. I had no intention to be offtopic! :)

On:

Copy files recipe (for general use)

Create copy-files.js|ts in aurelia_project/tasks folder

import * as gulp from 'gulp';
import * as project from '../aurelia.json';

export default function copyFiles() {
    let tasks = [],
        i = 0;

    for (let opts of project.copyFiles) {
        i++;
        let name = opts.name || `copyFilesTask${i}`;
        gulp.task(name, function () {
            return gulp.src(opts.sources).pipe(gulp.dest(opts.output));
        });

        tasks.push(name);
    }

    gulp.task('copyFiles', function (done) {

        var task = gulp.series(
            gulp.parallel.apply(gulp, tasks)
        );

        task(done);
    });
}

Add a new section to aurelia.json

"copyFiles": [
        {
            "name": "copyFonts",
            "output": "fonts",
            "sources": [
                "node_modules/font-awesome/fonts/*",
                "node_modules/bootstrap/dist/fonts/*"
            ]
        },
        {
            "name": "copyOtherRes",
            "output": "<destination>",
            "sources": [
                "<path1>/*.xyz",
                "<path2>/*.zyx"
            ]

        }
],

Modify aurelia_project/tasks/build.js|ts

export default gulp.series(
    readProjectConfiguration,
    ...
    copyFiles // new task
    ...
    writeBundles
);
EisenbergEffect commented 7 years ago

It might be appropriate to just have a Recipes section of the docs. Then under that we can have cli, binding, components, etc. Each one of those can be an article with a collection of recipes we can show in the sidebar.

adriatic commented 7 years ago

@martonsagi @AStoker @JeroenVinke We can conclude this slight turn of the main topic in this thread with a happy end - as @AStoker and I had a good conversation resulting with:

  1. The Recipes documentation is a great idea (initiated by @Thanood - a member of Monterey team)
  2. @martonsagi's Pacman is a likely solution for Monterey's immediate need, expected to be finally a part of aurelia-cli. This should of course be done with @EisenbergEffect's supervision and approval.

@martonsagi - let's continue the discussion on Pacman use in Monterey and aurelia-cli-pacman #398

stsje commented 7 years ago

It would be nice with a guide on how to update the Aurelia version with the CLI, and if it's possible to update individual aurelia packages.

EisenbergEffect commented 7 years ago

Everything related to updating would happen through npm. The Aurelia CLI doesn't have anything to do with that. So, the same practices for updating any npm library would apply to all Aurelia libraries, including the CLI itself. The only difference for the CLI is that there is a globally installed version of it and a locally installed version. The global version creates new projects and then it proxies all other commands through to the locally installed version. That allows you to control your tools versions on a per-project basis.

loaded02 commented 7 years ago

Upvote for a recipe to Manual bootstrapp an aurelia app with cli setup. In the docs it is only documented for JSPM and Webpack setup.

stsje commented 7 years ago

@loaded02 Heres one way of doing it in your index file. Could also just set remove the aurelia-app attribute and let the first required file be one of your own (then from there boostrap aurelia).

<script src="dist/vendor-bundle.js"></script>
<script>
  requirejs.config({
    skipDataMain: true
  });

  require(['environment'], function (environment) {
    require(['aurelia-bootstrapper']);
  });
</script>
jwx commented 7 years ago

I really like the concept of adding recipes! In my opinion, however, there's three different categories that's been mentioned in this discussion:

1) Tasks/functionality that the CLI should support without the need for additional code from the developer. This category includes, but is not limited to, tasks/functionality for configuring the project/configuration file, installing third party libraries, copying additional assets to a build, cleaning and publishing builds. (I know some of these are already in there, which is great.)

2) Documentation topics. Primarily this includes everything regarding how to configure the supported project options, for example shorthand paths, baseURL and bundling.

3) Recipies. This is basically everything not covered by any of the above. Typically, they are more complex than just simple configuration and also contain code. The recipies can very well be a part of the Aurelia documentation.

I believe that a good CLI that helps navigate through the deluge of javascript front-end development could really make a difference for Aurelia's adoption. For that reason, I think it's important that tasks/functionality that belongs in one of the first two categories don't end up in the third one. (Also, I'm of course willing to help out with turning the CLI into the awesome tool I think it could be.) @AStoker @JeroenVinke @EisenbergEffect

JeroenVinke commented 6 years ago

@AStoker @EisenbergEffect would you agree that Discourse is now the best place to share these recipes? if so we can probably close this

EisenbergEffect commented 6 years ago

I think Discourse is a good place to have a discussion and share recipes like this. However, I do think that we should cycle those recipes back into our core documentation, once they've been vetted by the community. That makes it easier for others in the future.

adriatic commented 6 years ago

This same issue was the main drive behind the AUCS project and details like au import recipes that @JeroenVinke just closed are of specific concern because I was writing that code with the hope that it will be used as the help in the process of building the CLI-next.

Alexander-Taran commented 6 years ago

@EisenbergEffect we can dump raw content into contrib and pick and choose whatever fits core docs. different level of standards. cant put whatever in core. yet raw has useful stuff.. examaple: https://github.com/aurelia-contrib/aurelia-getting-started/pull/27/files