search

gvwilson / sdxjs

Software Design by Example with JavaScript
Other
49 stars 12 forks source link

First reference to package.json needs an explanation #7

Open juananpe opened 1 year ago

juananpe commented 1 year ago

I think that this reference to package.json should be clarified https://github.com/gvwilson/sdxjs/blame/main/en/src/systems-programming/index.md#L76 (as far as I can tell, this is the first reference to that file, isn't it?)

zkamvar commented 1 year ago

Hi @juananpe, I'm curious why this was closed. This still seems to be the first mention of package.json.

I'm currently going through the book right now and I'm finding that this missing bit of setup information is causing me to get "SyntaxError: Cannot use import statement outside a module" errors because I don't have a package.json file.

juananpe commented 1 year ago

Hi @zkamvar, you are right. Let's open it again so @gvwilson can have a look at it.

zkamvar commented 1 year ago

I think what's missing is setup instructions and a disambiguation between node and npm (a la rustc and cargo in the rust book).

bouzlibop commented 4 months ago

In "Chapter 1: Introduction" in "Section 1.1: Who is our audience?" we can read that:

Like these three personas, readers should be able to: [...] • Install Node on their computer and run programs with it from the command line.

I guess it is assumed that the reader have a basic understanding of Node, npm and hence package.json. Maybe it would be worth at least to link to the documentation though.

zkamvar commented 4 months ago

I guess it is assumed that the reader have a basic understanding of Node, npm and hence package.json. Maybe it would be worth at least to link to the documentation though.

Yes, but what do you mean by a 'basic understanding' in this context? I would consider myself to have a basic understanding according to the criteria listed in the "Audience" section, but I did not stumble because of any lack of knowledge of what a package.json is.

I stumbled because of a variety of reasons: While I have worked with Node in the past, I did not have a clear disambiguation between JavaScript and Node. Any time I worked with Node, it was always through npm, but the resources that clearly disambiguate the two are not easily found, so my concept map was incomplete. Beyond that, the first thing we are presented with in the book is a single JS file and then a command to run that file from the command line. The unstated assumption is that we are working inside of a Node package, which requires either a hand-crafted or npm init'd packages.json file. I say this is an unstated assumption because it is very possible to write a stand-alone JS file to work by running node my-file.js outside of a package context (and is not at all uncommon in other programming languages).

My suggestion would be to 1) add something to the requirements that indicates to the user that they should know the differences between JavaScript and Node JavaScript and 2) clearly indicate that we are in a package context for the examples (my inserted text is in bold and the additional callout):

To start, let’s try creating a new module for listing the contents of a directory the way we would in Python or Java:

Examples in this book

All examples in this book are created within a Node package or module context created with npm init.