You just hit a route that doesn't exist... the sadness.
7 |4 | A Gatsby starter to get you started creating educational materials using Markdown 5 |
6 | 7 | ## Get Started 8 | 9 | 1. `npm install --global gatsby-cli` - make sure you're on Gatsby v2+ 10 | - See [docs here](https://next.gatsbyjs.org/docs/) if you need help 11 | 1. `gatsby new course-website https://github.com/btholt/gatsby-course-starter` 12 | 1. `cd course-website` 13 | 1. `npm run dev` 14 | 1. Open http://localhost:8000 in your browser 15 | 16 | ## Lessons 17 | 18 | The crux of this site is are the lessons. Provided are two examples. Each lesson needs a [frontmattter](https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/adding-markdown-pages.md#note-on-creating-markdown-files) `path`, `order`, and `title`. Generally you should make the `path` and the file name match for ease of finding it. 19 | 20 | - `path` - needs a leading slash. This will be slug of the lesson 21 | - `title` - will be the title displayed on the Table of Contents and on the page itself 22 | - `order` - the order of which the item should appear in the table of contents. should in `Welcome to {{ title }}
89 | ``` 90 | 91 | This fragment will be rendered where the `{{{ body }}}` tag is in the "main.hbs" file. 92 | 93 | Last, we need to render our templates and tell Oak to return them as the response. To do that, we first need to import the shared "hbs.ts" file into the "indexRoutes.ts" file. 94 | 95 | ```typescript 96 | import { Router } from "../deps.ts"; 97 | import hbs from "../shared/hbs.ts"; 98 | ``` 99 | 100 | Now, instead of returning text to the `ctx.response.body`, call the `hbs.renderView` method. You'll need to pass in the name of the template that you want to render (index) and any data that the template needs. In our case, it's just a "title" property. 101 | 102 | ```typescript 103 | import { Router } from "../deps.ts"; 104 | import hbs from "../shared/hbs.ts"; 105 | 106 | export function use(path: string, router: Router) { 107 | router.get(`${path}`, async (ctx) => { 108 | ctx.response.body = await hbs.renderView("index", { title: "Oak" }); 109 | }); 110 | } 111 | ``` 112 | 113 | Now run the application again and see what you get. 114 | 115 |  116 | 117 | OK! Not super impressive to look at, but we're now handling routing and returning dynamic templates. The next thing we need to do is style this page with some CSS. To do that, we need to figure out how to get Oak to return static files from a directory in our project. That's exactly what we'll do in the next section. 118 | 119 | **Bonus** - Create a "users" template and handle the view rendering in the "userRoutes.ts" file. 120 | -------------------------------------------------------------------------------- /lessons/welcome/intro.md: -------------------------------------------------------------------------------- 1 | --- 2 | path: "/intro" 3 | title: "Introduction" 4 | order: "1A" 5 | section: "1 - Welcome" 6 | description: "Burke covers the agenda for the Deno First Look workshop, talks about himself a little bit more than you would probably like, explains how to submit issues with this course and then pontificates on whether or not Deno is something that has a future and if we should be investing valuable time into learning it." 7 | --- 8 | 9 | Welcome to Deno First Look! 🎉 10 | 11 | ## Course Objective 12 | 13 | The objective of this course is to help you understand what Deno is, why on earth we need yet another JavaScript runtime (isn't Node.js good enough?), and how to build applications with Deno. Depending on when you see this, Deno may or may not have gained enough popularity in the JavaScript community to be prolific. The truth is we don't know if it will. But going through this course will ensure that you are not caught on your heels if it does. Either way, it just might open your mind to considering a different JavaScript runtime than what you may be used to. 14 | 15 | ## Who Are You? 16 | 17 | You should be a JavaScript developer with knowledge of Node.js. It's likely that if you're doing JavaScript development these days, that's a given. Node.js is used by most people in at least a development capacity - running local web servers, linting tools, ect. If you are using Node.js in production to host applications such as websites, web services, APIs, microservices, ect, then this course is especially applicable to you. Many of the exercises we'll go through in this course will specifically compare to functionality or libraries that exist today in Node. 18 | 19 | Knowledge of TypeScript is also a plus, but not required. We don't spend a lot of time getting into types or messing with TypeScript paticulars like interfaces, modules or the compiler details. There is quite a bit of that in Deno, but my feeling is that it adds a layer of confusion that isn't necessary to understand and be productive with Deno. It's also extremely off-putting if you don't know TypeScript, and I don't want to put you off. I want to excite you. 20 | 21 | If you would like to get a general knowledge of what TypeScript is, refer to [this video](https://channel9.msdn.com/posts/Anders-Hejlsberg-Introducing-TypeScript), which should be sufficient knowledge for this course. Normal JavaScript works just fine in TypeScript, and Deno supports both so I wouldn't worry too much about it. 22 | 23 | ## Where To File Issues 24 | 25 | The last time I did a course, I got a lot of PR's on mistakes made throughout. Most were grammatical or wrong images. There was a lot of misuse of "it's" vs "its". English is hard. Furthermore, my attention to detail isn't what it should be. What I'm trying to say is that mistakes in this course are inevitable, and I know that you will see what I cannot. If you do, I would love it if you would [open a pull request](https://github.com/burkeholland/deno-first-look/pulls) or [file an issue](https://github.com/burkeholland/deno-first-look/issues) on the GitHub repo. You can always find me on Twitter as well, although I try to avoid social media because I want to be happy so replies will be _seriously_ delayed. 26 | 27 | ## Who Am I? 28 | 29 |  30 | 31 | My name is Burke Holland, and I am a Content Engineer at Microsoft, where I do advocacy around VS Code, GitHub, Azure and all things JavaScript. I have a cursor on my face. 32 | 33 | I work with a team of great people and together we try and make Microsoft tools, services, and runtimes the best place in the world for JavaScript developers. I've been a JavaScript developer for 12 years. That's a long time in the world of JavaScript. I first fell in love with it when jQuery came out, and I have never looked back. I love everything about JavaScript, and I've never tired of writing it. I think it's a magical language that is uniquely easy to get started with and bizarrely well suited for applications of all types. 34 | 35 | I love teaching because it's simply the best way to learn anything. It also lets me connect with people and through this, I have learned that we are all far more alike than we are different. Mainly, we are all learning, and nobody has it all figured out. If you feel like you are the only one who doesn't understand things, let me assure you, you are not. There are at least 2 of us, and I am one. I love this diagram. I think it says it all. 36 | 37 |  38 | 39 | _Image Credit:_ [Alicia Liu](https://medium.com/counter-intuition/overcoming-impostor-syndrome-bdae04e46ec5) 40 | 41 | I live in Nashville with my wife, 3 teenage boys and 2 pugs. I'm a huge fan of Overwatch and I main Wrecking Ball. I know a lot of people don't like Wrecking Ball and they tell me all the time when we lose. I'm also an amateur craftsman, having built several pieces of modest furniture and doing remodel projects when my wife has new ideas for the house. There is a lot in common with woodworking and coding. Or knitting and coding. If you like coding, try picking up a different craft. Because you _are_ a craftsman. 42 | 43 | If you'd like to connect, you can [find me on Twitter](https://twitter.com/burkeholland). Although I treat Twitter kind of like Walmart - I only go in if I absolutely have to, so a better place to catch me is to [email me directly](mailto:burkeholland@gmail.com). I'd love to hear from you! 44 | 45 | ## Why Was This Course Created? 46 | 47 |  48 | 49 | I think the key to staying sane in this industry is to always be open to learning new things. It's also good to learn to learn-and-forget. You'll pick up things that stay with you and pay dividends down the road. Deno may be a ripple in a vast and endless ocean of JavaScript projects, libraries and frameworks. Or it may become the ocean itself. We don't know and that can cause distress. Learning about something removes the fear and intimidation that causes us to avoid things. This is true for everything in life, not just technology. Try it out and you'll see what I mean. If something scares you, learn more about it and will lose its power. 50 | 51 | There is also no idea that should be off the table when it comes to technology. Let's look at them all and pick the ones that work best for you, your brain, your team and your project. 52 | 53 | I have a [Frontend Masters course on VS Code](https://frontendmasters.com/courses/customize-vs-code/) as well if you'd like to check that out. That's a completely free course available to everyone. No subscription required. 54 | 55 | Thanks for staying with me, and I hope you enjoy this course: Deno First Look. 56 | -------------------------------------------------------------------------------- /lessons/what-is/secure-by-default.md: -------------------------------------------------------------------------------- 1 | --- 2 | path: "/what-is/secure-by-default" 3 | title: "Secure By Default" 4 | order: "2B" 5 | description: "Deno runtime is secure by default. This is in stark contrast to how Node works today, and it's important to understand why so that Deno's default locked down state doesn't feel so oppressive." 6 | section: "2 - What is Deno" 7 | --- 8 | 9 | > Switch to the [2-secure-by-default](https://github.com/burkeholland/deno-exercises/tree/2-secure-by-default) branch in the exercises to run the code in this section 10 | 11 | Deno is secure by default. When I hear things like this, they often come off to me as esoteric and frankly paranoid reasons to write an entirely new runtime. The truth is, though, that Node.js is not a secure runtime environment. When you run a Node program on your local machine, it has all the permissions that you do. If you have the write to access a file, so does that program. And most of us as developers are have root or admin access on our own machines. Even if we don't, it would be fairly easy for an npm module with bad intentions to do some nasty damage to your machine, or worse, your production environment. 12 | 13 | The browser is not like this. The browser is a secure sandbox that has zero access to your machine unless you grant it. Your phone is the same way. Think about it. Can apps on your phone access your location without your permission? Can they access your files and photos? No. You have to explicitly grant them the rights to do this. 14 | 15 | Similarly, the browser needs rights to access you location or camera, or even permission to send you a notification. 16 | 17 | But look at how this plays out in Node... 18 | 19 | The Node fs module lets you read and write to the file system. This means that you can pretty easily read sensitive information with the "fs" module - maybe something like this: 20 | 21 | ```javascript 22 | const fs = require("fs").promises; 23 | const path = require("path"); 24 | const homedir = require("os").homedir(); 25 | 26 | async function findEnvFiles(folderName, envFiles) { 27 | // read all the items in the current folder 28 | const items = await fs.readdir(folderName, { withFileTypes: true }); 29 | 30 | // iterate over each found item 31 | for (item of items) { 32 | // if the item is a directory, it will need to be searched 33 | if (item.isDirectory()) { 34 | // call this method recursively, appending the folder name to make a new path 35 | await findEnvFiles(path.join(folderName, item.name), envFiles); 36 | } else { 37 | // Make sure the discovered file is a .env file 38 | if (item.name === ".env" || item.name.indexOf(".env.") > -1) { 39 | // store the file path in the envFiles array 40 | envFiles.push(path.join(folderName, item.name)); 41 | } 42 | } 43 | } 44 | } 45 | 46 | async function readSecrets(envFiles) { 47 | let allSecrets = []; 48 | for (file of envFiles) { 49 | const secrets = await (await fs.readFile(file)).toString(); 50 | allSecrets.push(secrets); 51 | } 52 | return allSecrets; 53 | } 54 | 55 | async function main() { 56 | const envFiles = []; 57 | await findEnvFiles(homedir, envFiles); 58 | 59 | const secrets = await readSecrets(envFiles); 60 | 61 | secrets.forEach((secret) => { 62 | console.log(secret); 63 | }); 64 | } 65 | 66 | main(); 67 | ``` 68 | 69 | This code recursively reads your home directory for anything that looks like an .env file, and then logs that out. That's all your secrets, connection strings, etc. If I can get you to run this, then I can get your database connection strings, your OAuth keys - whatever you might be keeping in those local .env files. 70 | 71 | But how do I get you to run this? Aren't you smart enough NOT to run some package you don't trust or code that just looks nefarious? After all, YOU have to run this. So how do I get you to run it? 72 | 73 | The open-source world is such a wonderful place in which nobody would ever take advantage of you, right? Fortunately, that is by and large true, but by definition, open-source is open. Anyone can publish a module to npm. There is no review process. There is no security scan that occurs. Publish to npm and that module is immediately live for anyone to consume. So I could stick that code into an npm module and immediately make it available for anyone. But again, how do I get you to install and run this module? 74 | 75 | In his talk entitled, "How to hack a Node.js app", Asim Houssain details the extent to which the Node ecosystem is routinely used to exploit, hijack and otherwise maliciously execute code on unsuspecting machines. 76 | 77 | 78 | 79 | In this talk, he mentions many different ways that exploits can be done. But one of the most common and malicious is so simple that it's disappointing. 80 | 81 | ### Typo Squatting 82 | 83 | Typo squatting is when a package names itself in a commonly mistyped form of a legitimate module. In his talk, Wassim gives the example of the "crossenv" package. The "crossenv" package is a commonly used utility that normalizes the passing in of command line flags across Windows and Linux. It is widely used. Someone figured out that people commonly try to install "cross-env" instead of "crossenv" because they aren't sure what the exact name of the package is. One of those packages normalizes how programs are launched, the other reads your .env files - you know - where all your secrets and keys are stored and sends them to a remote server. WHICH IS EXACTLY WHAT THE CODE ABOVE DOES. 84 | 85 | Now that's pretty bad, but it can get much, much worse. 86 | 87 | In preparing for this course, I ran across a headline from zdnet... 88 | 89 |  90 | 91 | "You should consider your entire system compromised". 92 | 93 | That's heavy. And it can happen to anyone. And if you read that article, it says that even uninstalling the module doesn't mean you are safe. Because who knows what these packages installed and ran in the background? 94 | 95 | Node.js is simply not a safe runtime. It is wide open and is based on a wide open package system. While that makes is super convenient to use, it is by definition also relatively easy for seriously bad things to happen to your programs, even when you are paying close attention. There is a direct trade-off between convenience and security. Node has optimized for convenience. 96 | 97 | Deno is secure by default. That means that by default, programs have no access to read your file system, make an http call or perform other I/O related activities on your machine. You have to explicitly grant it access. We'll see how this works when we get into the syntax of Deno. You'll also get to see this tradeoff of convenience in action and decide for yourself whether or not "secure by default" should in fact be the default. 98 | 99 | Now this doesn't guarantee that you will be safe, but it makes it much harder for you to be victimized. It starts from a position of safety, and then asks you to opt out of that. Secure by default. 100 | -------------------------------------------------------------------------------- /lessons/oak/oak-router.md: -------------------------------------------------------------------------------- 1 | --- 2 | path: "/oak/oak-router" 3 | title: "The Oak Router" 4 | order: "7C" 5 | section: "7 - Oak web framework" 6 | description: "Burke introduces the Oak web framework for Deno" 7 | --- 8 | 9 | > Make sure you switch to the [7-oak-router](https://github.com/burkeholland/deno-exercises/tree/7-oak-router) branch to follow along with this section. 10 | 11 | Oak contains prebuilt Router middleware that will allow you to handle different routes, parameters and queries. It's basically doing a lot of string parsing and pattern matching that you would otherwise have to do yourself. 12 | 13 | Include the "Router" object in the Oak import. 14 | 15 | ```typescript 16 | import { Application, Router } from "https://deno.land/x/oak/mod.ts"; 17 | ``` 18 | 19 | Create a new "Router" instance below the "Application" instance. 20 | 21 | ```typescript 22 | const app = new Application(); 23 | const router = new Router(); 24 | ``` 25 | 26 | Create a handler for a "GET" request to "/" - or the root route. 27 | 28 | ```typescript 29 | import { Application, Router } from "https://deno.land/x/oak/mod.ts"; 30 | 31 | const app = new Application(); 32 | const router = new Router(); 33 | 34 | router.get("/", (ctx) => { 35 | ctx.response.body = "Welcome to Oak"; 36 | }); 37 | ``` 38 | 39 | Tell the `app` object to use the `router` as middleware. 40 | 41 | ```typescript 42 | import { Application, Router } from "https://deno.land/x/oak/mod.ts"; 43 | 44 | const app = new Application(); 45 | const router = new Router(); 46 | 47 | router.get("/", (ctx) => { 48 | ctx.response.body = "Welcome to Oak"; 49 | }); 50 | 51 | app.use(router.routes()); 52 | 53 | console.log(`Now listening on http://0.0.0.0:3000`); 54 | await app.listen("0.0.0.0:3000"); 55 | ``` 56 | 57 | Run the app with `deno run --allow-net app.ts` 58 | 59 | You should see the same thing you had before - a simple page saying "Welcome to Oak". Note, though, that this route will only respond to the root route, and only if the request is a GET. Before, the application would respond to any request at all. 60 | 61 | ## Adding additional routes 62 | 63 | Add an additional "users" route that responds to the "/users" route. It should come before the `app.use(router.routes())` line. 64 | 65 | ```typescript 66 | router.get("/", (ctx) => { 67 | ctx.response.body = "Welcome to Oak"; 68 | }); 69 | 70 | router.get("/users", (ctx) => { 71 | ctx.response.body = `Welcome User`; 72 | }); 73 | ``` 74 | 75 | Add a third route which also listens to the "/users" route, but listens for an additional "/:name" param and echoes the value back out. 76 | 77 | ```typescript 78 | router.get("/", (ctx) => { 79 | ctx.response.body = "Welcome to Oak"; 80 | }); 81 | 82 | router.get("/users", (ctx) => { 83 | ctx.response.body = `Welcome User`; 84 | }); 85 | 86 | router.get("/users/:name", (ctx) => { 87 | ctx.response.body = `Welcome ${ctx.params.name}`; 88 | }); 89 | ``` 90 | 91 | Run the application again and test the different routes. Try passing in "localhost:3000/users/YOUR_NAME". It should be echoed back out to you. 92 | 93 | ## Organizing routes like Express 94 | 95 | The Express generator puts all the routes in files that correspond to their base route. For instance, the "/" routes are contained in the "routes/index.js" file. The "/user" routes are all contained in the "routes/users.js" file. In this section, you'll refactor your code to move the routes into their own folder. 96 | 97 | ### Creating a deps.ts file 98 | 99 | In order to do that, we're going to need to access our dependencies from more than one file. Instead of importing URL's all over the application, let's move all our imports into a single "deps.ts" file. 100 | 101 | - Cut the Oak import line from the top of the "app.ts" file. 102 | - Create a file in the root called "deps.ts" 103 | - Paste in the Oak import 104 | - Export the `Application` and `Router` objects. 105 | 106 | ```typescript 107 | import { Application, Router, Context } from "https://deno.land/x/oak/mod.ts"; 108 | export { Application, Router, Context }; 109 | ``` 110 | 111 | In the "app.ts" file, import the `Application` and `Router` objects from the "deps.ts" file 112 | 113 | ```typescript 114 | import { Application, Router } from "./deps.ts"; 115 | ``` 116 | 117 | ### Creating routes files 118 | 119 | Right now, all of the routes are in the main `app.ts` file. This is fine when we only have 3 routes, but what happens when we have 100? A better solution would be to have one file per "route". 120 | 121 | For instance, we can create a file that handles all requests to "/". It doesn't matter if they are a GET, POST, PUT or if the path has a parameter on it, we can put all of that logic in a single file. 122 | 123 | - Create a folder called "routes" 124 | - Create a file called "indexRouter.ts" in the "routes" folder. 125 | - Import the "Router" object from the "deps.ts" file 126 | 127 | ```typescript 128 | import { Router } from "../deps.ts"; 129 | ``` 130 | 131 | Create a function called "use" which will accept a path and a reference to the router object. This will allow us to pass in the path we want this function to handle as well as the router object we defined in the `app.ts` file. 132 | 133 | ```typescript 134 | import { Router } from "../deps.ts"; 135 | 136 | export function use(path: string, router: Router) {} 137 | ``` 138 | 139 | Move the index route to this new "indexRouter.ts" file 140 | 141 | ```typescript 142 | import { Router } from "../deps.ts"; 143 | 144 | export function use(path: string, router: Router) { 145 | router.get(`${path}`, async (ctx: Context) => { 146 | ctx.response.body = "Welcome to Oak"; 147 | }); 148 | } 149 | ``` 150 | 151 | We use the "path" variable and append all routes to that object. That's so that we can specify the path in the "app.ts" file for all our routers. As we add more and more routers, it's going to be important to know what router is handling what path by just by looking at the "app.ts" file. 152 | 153 | Import the new file as `indexRouter` at the top of the "app.ts" file 154 | 155 | ```typescript 156 | import { Application, Router } from "./deps.ts"; 157 | import * as indexRouter from "./routes/indexRouter.ts"; 158 | ``` 159 | 160 | Tell the router to the "/" path and the existing "router" object. 161 | 162 | ```typescript 163 | indexRouter.use("/path", router); 164 | ``` 165 | 166 | Run the app again to make sure the index route still works. 167 | 168 | Repeat the same thing for the "user" routes with a file called "routes/userRouter.ts". Your final "app.ts" should look like this... 169 | 170 | ```typescript 171 | import { Application, Router } from "./deps.ts"; 172 | import * as indexRouter from "./routes/indexRouter.ts"; 173 | import * as userRouter from "./routes/userRouter.ts"; 174 | 175 | const app = new Application(); 176 | const router = new Router(); 177 | 178 | indexRouter.use("/", router); 179 | userRouter.use("/users", router); 180 | 181 | app.use(router.routes()); 182 | 183 | console.log(`Now listening on http://0.0.0.0:3000`); 184 | await app.listen("0.0.0.0:3000"); 185 | ``` 186 | 187 | Now that we've got a proper routing structure in place, let's turn our attention to the next big problem to solve - and that's how to use templates to return HTML instead of just returning text. 188 | -------------------------------------------------------------------------------- /lessons/webserver/reading-parameters.md: -------------------------------------------------------------------------------- 1 | --- 2 | path: "/webserver/reading-parameters" 3 | title: "Reading the query string" 4 | order: "6B" 5 | section: "6 - Building a Webserver" 6 | description: "Burke looks at how to build a simple web server with Deno" 7 | --- 8 | 9 | > Make sure you are on the [6-reading-the-query-string](https://github.com/burkeholland/deno-exercises/tree/6-reading-the-query-string) branch to follow along with this section. 10 | 11 | ## Reading query parameters 12 | 13 | An important part of any web server is the ability to handle parameters. These could be query string parameters or parameters passed on the body. Let's look at how to do both of those things with our simple web server. 14 | 15 | Let's modify this app so that it returns a "Hello" when we pass in a `name` parameter on the query string. Like this... 16 | 17 | ```bash 18 | http://localhost:3000?name=World 19 | ``` 20 | 21 | How do we get that "name" parameter? Well, we need to parse the query string to do that. The Deno web server is just that, and it doesn't come with an easy way to just get the query string parameters. But we can get them from the request. 22 | 23 | The `req.url` object holds the URL fragment - which is everything that comes after the address and port. You can use the browser [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object to parse out the query string parameters. 24 | 25 | > Note that a "/" gets prepended to the "?" in a query string by the browser and URLSearchParams can't handle this. So we'll strip off the first character with substring(). 26 | 27 | In the for loop, use the `URLSearchParams` object to parse the `req.url` and get the name. 28 | 29 | ```typescript 30 | for await (const req of server) { 31 | const searchParameters = new URLSearchParams(req.url.substring(1)); 32 | const name = searchParameters.get("name"); 33 | 34 | req.respond({ 35 | body: "