First time user notes on Quick Start Guide, part 1

DoneJS
1

I’m just getting started with DoneJS, using these messages to capture my experiences with donejs - Quick start guide. Sorry if this seems “negative” and petty, but I think it important to capture the novice experience:

  • I suspect the npm install -g donejs command should be run as root (assuming -g means global), and the subsequent commands run as a nonprivileged user, but that isn’t specified.

  • Under Add it to the page, my index.stache file has the following line which isn’t shown in the guide’s model:
    <h1>{{message}}</h1>

  • I made a typo in my editing of index.stache (entered “<can-import from-"bootstrap/less/bootstrap.less!" />”, note from- instead of from=) and even after correcting it, the web page still shows my typo. This happens even if I open a new browser session, so the typo is somehow “stuck” in the DoneJS mechanism. Restarting the donejs server did clear the problem.

  • Again under Navigate between pages, the model doesn’t exactly match my src/home.component file, which contains these additional lines:

p { font-weight: bold; }
<p>{{message}}</p>
<script type="view-model">
import Map from 'can/map/';
import 'can/map/define/';
export default Map.extend({
define: {
message: {
value: 'This is the chat-home component'
}
}
});
</script>

  • My src/app.js and src/index.stache also differ significantly from the models in this section of the guide. src/index.stache shows some but not all of the edits I made earlier under Add it to the page. Not knowing better, i left in my earlier edits to this file, see below for results.

  • I attempted to reload my browser at port 8080 as instructed, but now confronted errors about bootstrap not being found. Discovered bootstrap was directly loaded under my ~/node_modules, so logged into ~/donejs-chat and reran npm install bootstrap --save from there, which fixed that problem. Apparently the user should install bootstrap from ~/donejs-chat rather than ~.

Then my browser said:

Error: Error loading "donejs-chat@0.0.0#index.stache!done-autorender" at <unknown>
Error loading "done-autorender" at file:/home/ec2-user/donejs-chat/done-autorender.js
ENOENT, open '/home/ec2-user/donejs-chat/done-autorender.js'

At this point, autorender package was installed at ~/donejs-chat/node_modules/done-autorender.

  • I then reloaded the server (in initial shell window, ctrl-C, donejs develop) and the above error did not recur. However, I now had two vertically stacked “donejs chat” displays on my browser, because I had added the second edit (above) to my first rather than replacing it. Replaced the section rather than adding it and my demo page now appears same as the guide’s sample.

Thanks for reading. I will await your comments on this section before proceeding with the rest of the Guide.

P.S.: To clarify, I’m hoping someone can let me know whether I’ve followed the Guide correctly thus far or whether I should back up or start over before going further with it.

Also, I notice at donejs - Setting Up DoneJS that specific versions of Node and npm are required by DoneJS. If still applicable, I strongly recommend that information be added to the Guide. The system I’m testing with (Amazon Linux) is running node v0.10.36 and npm 1.3.6. The above page lists npm 2.x or 3.x as a requirement. Should I be concerned?

2

It’s true that this is the default behavior when you install Node through the download on the website, but I wouldn’t recommend using Node this way because you will definitely run into permissions issues down the road. I would recommend uninstalling Node and reinstalling using nvm: https://github.com/creationix/nvm/blob/master/README.markdown. This is beneficial for a few reasons:

  1. You no longer need sudo.
  2. As a result of number 1, this almost completely removes the likelihood of running into permissions issues in the future.
  3. You can switch node versions and each version of node can have its own set of global modules installed, so you can do things like switch to node 0.12 and install an older version of steal and steal-tools, then switch to node 5.8 and install the latest versions of steal and steal-tools. This comes in very handy.
3

Thanks for pointing this one out. I’m pretty sure this is a known issue with the top level template. I’m not sure if we have a solution for it, yet, since this is a result of how the SSR server caches the page (or something to that effect), but this is something that could at least be pointed out in the documentation. Would you mind opening an issue here: Sign in to GitHub · GitHub

This is one of those things that I’ve just gotten used to doing, so I’m guilty of working with it instead of opening an issue for it. This is why the type of feedback you’re providing is SUPER valuable. We don’t look at pointing out even the smallest issues as being negative or petty.

4

I think it’s a good point you make here. It could save people some time to put a single sentence at the beginning of every guid pointing them to the prerequisites. Care to open an issue? Sign in to GitHub · GitHub

I think our test coverage includes testing all of the mentioned versions of node and npm. So, the npm version sounds concerning since you’re basically on your own in finding possible bugs in the wild west of npm@1.3.6. This also adds more context to your comment about installing global modules using sudo. :slight_smile:

5

With what you’ve mentioned about the environment you’re running. I would recommend trying the guide again with a supported (tested) npm version, so we can at least be sure you’re not running into issues that are caused by running an unsupported version.

6

Thanks, @marshallswain. I will open the issues as you recommend. I’ve upgraded to npm 3.8.2. So far have not resorted nvm. Further findings:

  • Some of the procedures in the Guide have me “Update file to look like this;” others say to “update the file:” or “update file to:” which is ambiguous when the existing file contents don’t match the nongreen parts of the model: do I conform to the model or keep my contents?

    Would changing all of these to “Update file to look like this” (meaning just discard anything that doesn’t match the model) be acceptable?

    I’ll give another example; this one was fatal. ~//donejs-chat/src/messages started as:

import Component from 'can/component/';
import Map from 'can/map/';
import 'can/map/define/';
import './messages.less!';
import template from './messages.stache!';

export const ViewModel = Map.extend({
  define: {
    message: {
      value: 'This is the chat-messages component'
    }
  }
});

export default Component.extend({
  tag: 'chat-messages',
  viewModel: ViewModel,
  template
});

Following the guide, I then edited this to:

import Component from 'can/component/';
import Map from 'can/map/';
import 'can/map/define/';
import './messages.less!';
import template from './messages.stache!';
import Message from '../models/message';

export const ViewModel = Map.extend({
  define: {
    message: {
      value: 'This is the chat-messages component'
    }
  }
  send(event) {
    event.preventDefault();

    new Message({
      name: this.attr('name'),
      body: this.attr('body')
    }).save().then(msg => this.attr('body', ''));
  }
});

export default Component.extend({
  tag: 'chat-messages',
  viewModel: ViewModel,
  template
});

This caused a fatal error:

Potentially unhandled rejection [5] SyntaxError: file:/home/ec2-user/donejs-chat/src/messages/messages.js: Unexpected token (14:2)

   12 |     }
   13 |   }
   14 |   send(event) {
      |   ^
   15 |     event.preventDefault();
   16 |
   17 |     new Message({

I then removed the offending define: clause and my app started working. “Update file to look like this” might have prevented this.

  • npm install steal-socket.io --save (with npm 3.8.1) succeeded with warnings:
npm WARN optional Skipping failed optional dependency /documentjs/chokidar/fsevents:
npm WARN notsup Not compatible with your operating system or architecture: fsevents@1.0.8
npm WARN optional Skipping failed optional dependency /steal-tools/chokidar/fsevents:
npm WARN notsup Not compatible with your operating system or architecture: fsevents@1.0.8
npm WARN donejs-chat@0.0.0 No repository field.
npm WARN donejs-chat@0.0.0 No license field.

I have no idea how significant these warnings are.

  • Enable a real-time connection not only didn’t enable a real-time connection, it apparently stopped the app from accepting new messages. Removed the real-time code and I can again log messages, need to refresh other browser window to see them.

  • Next section: Production build. Ran donejs build, stopped and restarted donejs as NODE_ENV=production donejs start, after which the Guide tells me I should see a Developer Tools page at localhost:8080, however, I’m seeing the same “chat” app as before. Help!

7

Yes. I’m pretty sure that in all cases you should completely replace the contents of the file with the code in each example. The green lines are to show you what’s new. We don’t show the removed lines to keep it clean. I think this is a fair candidate for another issue regarding clearer wording. We don’t want any ambiguity.