Getting-Started

Right, so you’ve written some code. Congratulations. Now comes the fun part: writing code that doesn’t always run. I know, it sounds like the opposite of progress, but trust me, conditional compilation is one of those features you’ll quickly wonder how you ever lived without. It’s how you tell the compiler, “Hey, only include this chunk of code if a certain condition is met.” We use this for everything from targeting different operating systems and CPU architectures to enabling expensive debug-only checks or entirely experimental features.

Right, so you’ve graduated from a single crate. Congratulations. Your codebase now looks less like a neat little cottage and more like a sprawling, slightly concerning, hoarder’s mansion. Welcome to the big leagues, where you need a tool to manage the chaos. That tool is cargo workspace. A workspace is Cargo’s way of saying, “I see you have a problem with creating too many separate projects. Let me help you organize that problem.” It’s a set of member crates—libraries and binaries—that all get built from the same top-level directory, sharing a common Cargo.lock file and target directory. This is the killer feature: no more compiling serde six separate times for six inter-related crates. Your CPU and your time will thank me.

Right, let’s talk about the target/ directory. This is where Cargo, our ever-faithful and occasionally overzealous build manager, dumps everything it creates while trying to turn your beautiful, readable Rust code into a brutally efficient binary. It’s the backstage area of our production—utterly essential, usually a mess, and you only go poking around in there when something has gone horribly wrong or you need to find a specific prop. Think of your src/ directory as your clean, well-organized kitchen. The target/ directory is what happens when you actually cook the meal: bowls everywhere, flour on the floor, and the sink full of dishes. It’s the byproduct of the creative process. You wouldn’t serve your guests from this chaos, and you almost never need to version control it (add target/ to your .gitignore right now, I’ll wait).

Right, let’s talk about the two different hats your code wears: the comfy, forgiving “debug” sweatpants and the performance-optimized, no-nonsense “release” suit. You’ve probably already seen this in action. When you run cargo build, it defaults to the debug mode. Your code compiles relatively quickly, but the resulting binary is large, slow, and packed with debugging information. When you run cargo build --release, it takes longer, but you get a lean, mean, executing machine.

Right, let’s get our hands dirty with the actual project structure. You’ve run cargo new my_cool_project and you’re staring at a few files. The Cargo.toml is the manifest, the dinner menu for your application. But the kitchen, the place where the actual cooking happens, is the src directory. This is where we live. By sacred convention, enforced by Cargo with the subtlety of a brick through a window, your executable’s main entry point must be src/main.rs. Not main.rs, not source/main.rs, not please_work/main.rs. src/main.rs. Break this rule and Cargo will simply shrug and refuse to build a binary. It’s not being difficult; it’s being relentlessly consistent, and you’ll come to love it for that.

Right, so you’ve run cargo new, you’ve got a directory, and you’re staring at src/main.rs. Let’s not just run it; let’s dissect it. This isn’t just a “hello world” program; it’s a Rosetta Stone for understanding how Rust thinks. Every single character here is doing heavy lifting. Here’s the canonical, almost religiously significant piece of code you’ll find: fn main() { println!("Hello, world!"); } Let’s break it down line by sinister line.

Before you go downloading anything, let’s get one thing straight: you don’t need a local setup to start playing with TypeScript. The TypeScript team, in a moment of pure genius and empathy, built the TypeScript Playground. Think of it as a digital sandbox where you can build castles of code without getting sand in your laptop’s keyboard. It’s the perfect place to experiment, share ideas, and, most importantly, prove to a colleague that your type definition is superior to theirs, all without the ceremony of npm install.

Right, so you’ve run tsc on your index.ts file. You saw it flash by in the terminal, and now you have a new index.js file sitting there. It feels a bit like magic, but we’re not here for magic tricks. We’re here to understand the engineering. Let’s crack open that output file and see what the compiler actually did for us. This is where you go from “it just works” to knowing why it works.

Right, let’s get our hands dirty. We’ve set up the machinery; now let’s see what it actually does. The core premise of TypeScript is simple: it’s JavaScript with a type system slapped on top. But don’t let that simplicity fool you—this is where the magic, and more importantly, the sanity, happens. You already know how to write this in JavaScript: // plain-old-javascript.js function greet(name) { return "Hello, " + name; } console.log(greet("Alice")); // "Hello, Alice" console.log(greet(42)); // "Hello, 42" ... wait, what? The JavaScript version is perfectly happy, if a bit naive. It will cheerfully concatenate a number onto a string, which might not be what you intended. It’s like a friendly golden retriever that brings you a shoe instead of a ball—the enthusiasm is there, but the execution is flawed.

Right, so you’ve got TypeScript installed. You can run tsc --version and feel a brief moment of power. Now you’re staring at an empty project directory. You might be tempted to just run tsc main.ts and call it a day. Don’t. That’s like using a particle accelerator to crack a walnut. It works, but you’re missing the point and you’ll eventually create a black hole that swallows your project whole. The proper way to wield this tool is with a tsconfig.json file. This is your project’s mission control, and we’re going to build it from the ground up.

Alright, let’s get one thing straight: compiling your TypeScript with tsc every single time you want to run a tiny script is a fantastic way to lose your will to live. It’s the programming equivalent of having to assemble a car engine just to drive to the mailbox. You’re a developer, not a build-system masochist. This is where ts-node and tsx come in—they’re your power tools for skipping the “generate a .js file” middleman and running your beautiful TypeScript code directly.

Alright, let’s get our hands dirty. You’ve written a beautiful piece of TypeScript code in a file called greeter.ts. It’s pristine. It’s elegant. It has type annotations. Your browser, however, couldn’t care less about type annotations. It speaks JavaScript, and frankly, it finds your sophisticated types a bit pretentious. This is where tsc, the TypeScript compiler, comes in. Its job is to be the translator, converting your lofty TypeScript (greeter.ts) into the plain, workmanlike JavaScript (greeter.js) that the browser or Node.js can actually execute.

Alright, let’s get you set up to actually use TypeScript. We’re going to do this the right way, which means I’m going to talk you out of installing it globally almost immediately. Stick with me. The first thing you need is Node.js and its trusty sidekick, npm (or its speedier, modern cousin, pnpm or yarn). If you don’t have Node.js on your machine, go grab the LTS version from the official website. I’ll wait. Don’t worry, this isn’t the kind of book where I make you feel bad for not having things installed beforehand. We’ve all been there.

Right, let’s get our hands dirty with the hugo command itself. Forget the gentle, hand-holding hugo help output; we’re going to dissect the thing you’ll be typing into your terminal a thousand times. This isn’t a list of every flag—that’s what --help is for. This is a curated tour of the flags and subcommands you’ll actually use, along with the ones that will bite you if you don’t know they’re there.

Right, so you’ve got a site full of content, some themes, maybe a few fancy shortcodes. It’s all sitting there in your content and layouts directories, which is great, but it’s not a website yet. It’s a collection of ingredients. Running hugo build is the act of turning those ingredients into a finished, served-ready meal. Or, less charitably, it’s where Hugo takes your beautifully organized thoughts and flattens them into a gigantic pile of static HTML files. It’s brilliant, it’s fast, and it’s the whole point of using a static site generator.

Right, so you’ve got a Hugo site. It’s a pile of templates, content files, and configuration sitting on your hard drive. Not exactly a thrilling view for a web browser. The hugo server command is the magician that brings this inert pile of code to life, right in front of you. It’s your development playground, your live-preview engine, and your number one tool for actually seeing what you’re building. Think of it less as a “server” and more as a hyper-observant construction foreman. You change a file, he yells “EVERYTHING IS DIFFERENT NOW,” and instantly rebuilds the site so you can see the result. It’s glorious.

Right, you’ve got Hugo installed. Don’t get cocky. That was the easy part. Now we get to the command that feels like a magic spell but is really just a very organized, slightly opinionated file clerk: hugo new site. Think of this command as your site’s ground zero. It doesn’t just make a folder; it builds the entire scaffold, the skeleton, the filing system that Hugo expects to find every time it goes to build your site. Run it, and for the love of all that is holy, give your project a sensible name. Not my-website. Not test-site-7. You’re better than that.

Alright, let’s cut through the noise on this one. The “Hugo Extended vs. Standard” debate seems like a classic case of overcomplicating a simple choice, but it actually matters for exactly one reason: you want to use SCSS. Let’s be blunt: if you don’t know what SCSS (or SASS) is, you almost certainly want the Standard version. Go make a sandwich, this section isn’t for you yet. The Extended version is a heavier toolbox for a specific job. If you’re just writing CSS or using a pre-built theme, Standard is simpler, smaller, and perfectly capable.

Alright, let’s get you set up with Hugo. This isn’t brain surgery, but there are a few paths you can take, and some are decidedly smoother than others. I’ll lay out your options, give you the commands, and more importantly, tell you which route I’d take and why. The goal is to get from zero to a running local server in under five minutes, without any cryptic error messages. The Homebrew Method (macOS & Linux) If you’re on a Mac or running a decent Linux distribution, Homebrew is, by a wide margin, my preferred package manager. It’s not just easy; it’s sane. It handles dependencies, updates, and installations in a way that feels like the developers actually use their own tool.