Creating a Fresh project in Deno - Mechanics & Internals

Overview - Creating a Fresh project

What is it?

Creating a Fresh project means starting a new web application using Fresh, a modern web framework built on Deno. Fresh helps you build fast, interactive websites with minimal setup and no build step. It uses islands architecture to only update parts of the page that need it, making your app efficient and easy to maintain.

Why it matters

Without Fresh, building web apps often involves complex tools, slow builds, and heavy JavaScript bundles that slow down websites. Fresh solves these problems by simplifying setup and focusing on speed and simplicity. This means users get faster websites, and developers spend less time configuring tools and more time building features.

Where it fits

Before creating a Fresh project, you should know basic JavaScript or TypeScript and have a general idea of web development concepts like HTML and HTTP. After learning to create a Fresh project, you can explore routing, server-side rendering, and client-side interactivity within Fresh to build complete web apps.

Mental Model

Core Idea

Creating a Fresh project sets up a ready-to-use web app framework that runs on Deno, letting you build fast, modern websites with minimal fuss.

Think of it like...

Starting a Fresh project is like getting a new, fully equipped kitchen where all the tools and ingredients are ready, so you can start cooking your favorite meals without delay.

┌───────────────────────────────┐
│       Create Fresh Project     │
├──────────────┬────────────────┤
│  Deno CLI    │  Fresh Template │
├──────────────┴────────────────┤
│  Project Folder with:          │
│  - main.ts (entry point)       │
│  - routes/ (page files)        │
│  - islands/ (interactive parts)│
│  - static/ (assets)            │
└───────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

Install Deno Runtime

Concept: You need Deno installed to run Fresh projects because Fresh runs on Deno, not Node.js.

Go to deno.land and follow the instructions to install Deno on your computer. You can check installation by running `deno --version` in your terminal.

Result

Deno is installed and ready to run commands.

Knowing that Fresh depends on Deno helps you understand why you must install Deno first before creating or running Fresh projects.

2

Foundation

Use Fresh CLI to Create Project

Concept: Fresh provides a command-line tool to quickly scaffold a new project with all necessary files and folders.

Run `deno run -A --unstable https://fresh.deno.dev` in your terminal. It will prompt you for a project name and create a folder with starter files.

Result

A new folder with a Fresh project template is created on your computer.

Using the Fresh CLI automates setup, so you don't have to manually create files or configure settings.

3

Intermediate

Understand Project Folder Structure

🤔Before reading on: do you think the 'routes' folder contains code for pages or styles? Commit to your answer.

Concept: Fresh organizes your app into folders like 'routes' for pages and 'islands' for interactive components.

Inside your project folder, you'll see: - `routes/`: files here define pages and URLs. - `islands/`: components that update dynamically on the client. - `static/`: static files like images. - `main.ts`: the app entry point.

Result

You know where to add pages and interactive parts in your project.

Understanding the folder roles helps you organize your code and know where to add new features.

4

Intermediate

Run Development Server Locally

🤔Before reading on: do you think running the dev server requires building the project first? Commit to your answer.

Concept: Fresh includes a development server that watches your files and reloads the app automatically.

Inside your project folder, run `deno task start`. This starts a local server at http://localhost:8000 where you can see your app live and changes update instantly.

Result

Your Fresh app runs locally and updates as you edit files.

Knowing how to run the dev server lets you test and develop your app interactively.

5

Advanced

Customize Project with TypeScript

🤔Before reading on: do you think Fresh supports JavaScript only or also TypeScript? Commit to your answer.

Concept: Fresh uses TypeScript by default, letting you write safer and clearer code with types.

All your project files can use `.ts` or `.tsx` extensions. You can add types to variables and functions to catch errors early. Fresh and Deno handle TypeScript without extra setup.

Result

Your project uses TypeScript for better code quality and fewer bugs.

Understanding TypeScript support helps you write more reliable code and leverage modern language features.

6

Expert

Leverage Islands Architecture Setup

🤔Before reading on: do you think Fresh sends all JavaScript to the browser or only parts? Commit to your answer.

Concept: Fresh uses islands architecture to send JavaScript only for interactive parts, improving performance.

When you create interactive components inside the `islands/` folder, Fresh automatically hydrates only those parts on the client. This reduces JavaScript size and speeds up page loads.

Result

Your app loads faster because only needed JavaScript is sent to the browser.

Knowing how islands architecture works helps you build fast apps by minimizing unnecessary code sent to users.

Under the Hood

Fresh projects run on Deno, which executes TypeScript and JavaScript directly without a build step. The Fresh CLI scaffolds a project with a specific folder structure where 'routes' define server-rendered pages and 'islands' contain client-hydrated interactive components. When running, Fresh serves pages rendered on the server and injects minimal JavaScript only for islands, using Deno's native ES module support and HTTP server capabilities.

Why designed this way?

Fresh was designed to avoid the complexity and slow build times of traditional JavaScript frameworks. By leveraging Deno's modern runtime and ES modules, Fresh eliminates bundling and transpiling steps. The islands architecture was chosen to optimize performance by sending only necessary JavaScript to the client, improving load times and user experience.

┌───────────────┐       ┌───────────────┐
│  Fresh CLI    │──────▶│ Project Files │
└───────────────┘       └───────────────┘
         │                      │
         ▼                      ▼
┌─────────────────┐     ┌─────────────────┐
│ Deno Runtime    │     │ Folder Structure │
│ - Runs TS/JS    │     │ - routes/       │
│ - Serves HTTP   │     │ - islands/      │
└─────────────────┘     └─────────────────┘
         │                      │
         ▼                      ▼
┌─────────────────────────────────────────────┐
│ Server renders pages + hydrates islands only│
└─────────────────────────────────────────────┘

Myth Busters - 3 Common Misconceptions

Quick: Does Fresh require a build step before running the app? Commit yes or no.

Common Belief: Fresh needs a build step like other frameworks to compile code before running.

Reality: Fresh runs directly on Deno without any build step, using native TypeScript and ES modules.

Why it matters: Expecting a build step can confuse beginners and slow down development by adding unnecessary complexity.

Quick: Does Fresh send all JavaScript code to the browser? Commit yes or no.

Common Belief: Fresh sends the entire JavaScript bundle to the browser for every page.

Reality: Fresh only sends JavaScript for interactive islands, keeping pages lightweight and fast.

Why it matters: Thinking all code is sent can lead to inefficient coding and slower apps.

Quick: Can you use Fresh without Deno installed? Commit yes or no.

Common Belief: Fresh can run on Node.js or other runtimes without Deno.

Reality: Fresh is built specifically for Deno and requires it to run.

Why it matters: Trying to run Fresh without Deno causes errors and wasted time troubleshooting.

Expert Zone

1

Fresh's no-build approach relies on Deno's native ES module support, which means you must use modern browsers or polyfills for compatibility.

2

The islands architecture requires careful component design to balance interactivity and performance; overusing islands can negate speed benefits.

3

Fresh's routing is file-based but supports dynamic routes and middleware, allowing flexible app structures beyond simple pages.

When NOT to use

Fresh is not ideal if you need extensive client-side state management or complex single-page app features; in those cases, frameworks like React or Vue with client-side routing may be better.

Production Patterns

In production, Fresh projects often deploy on edge platforms or serverless environments that support Deno, leveraging Fresh's fast cold starts and minimal JavaScript to deliver highly performant web apps.

Connections

Server-Side Rendering (SSR)

Fresh builds on SSR principles by rendering pages on the server before sending to the client.

Understanding SSR helps grasp how Fresh delivers fast initial page loads and SEO-friendly content.

Islands Architecture

Fresh implements islands architecture to optimize client-side JavaScript delivery.

Knowing islands architecture clarifies why Fresh sends minimal JavaScript and how it improves performance.

Modern Web Browsers

Fresh depends on modern browsers supporting ES modules and JavaScript features.

Awareness of browser capabilities helps understand Fresh's no-build, native module approach.

Common Pitfalls

#1 Trying to run Fresh project without Deno installed.

Wrong approach:

deno task start (without installing Deno first)

Correct approach:

Install Deno from deno.land first, then run `deno task start`.

Root cause:

Not knowing Fresh requires Deno runtime causes confusion and errors.

#2 Editing files outside the 'routes' or 'islands' folders for pages or components.

Wrong approach:

Adding page code directly in random folders without following Fresh structure.

Correct approach:

Place page files inside 'routes/' and interactive components inside 'islands/'.

Root cause:

Misunderstanding Fresh's folder conventions leads to code not working or being ignored.

#3 Expecting a build step and trying to run a build command that doesn't exist.

Wrong approach:

Running `npm run build` or similar in Fresh project.

Correct approach:

Use `deno task start` to run the dev server directly without building.

Root cause:

Assuming Fresh works like traditional Node.js frameworks causes wasted effort.

Key Takeaways

Creating a Fresh project sets up a modern web app framework running on Deno with minimal setup.

Fresh uses a special folder structure where 'routes' define pages and 'islands' hold interactive components.

Fresh runs without a build step, leveraging Deno's native TypeScript and ES module support.

The islands architecture sends JavaScript only for interactive parts, making apps fast and efficient.

Understanding Fresh's dependency on Deno and its conventions is key to successful project creation and development.

Practice

1. What command do you use to create a new Fresh project in Deno?

easy

A. deno fresh create

B. deno run -A --unstable https://fresh.deno.dev/init <project-name>

C. deno init fresh

D. deno start fresh

Solution

1. Step 1: Understand Fresh project creation command

   The official way to create a Fresh project is by running a Deno script from the URL https://fresh.deno.dev/init with the project name as argument.

2. Step 2: Identify the correct command syntax

   The command includes 'deno run -A --unstable' followed by the URL and the project name, exactly as in deno run -A --unstable https://fresh.deno.dev/init <project-name>.

3. Final Answer:

   deno run -A --unstable https://fresh.deno.dev/init <project-name> -> Option B

4. Quick Check:

   Fresh project creation = deno run -A --unstable https://fresh.deno.dev/init <project-name> [OK]

Hint: Remember the URL and flags for Fresh init command [OK]

Common Mistakes:

• Using 'deno fresh create' which is not a valid command
• Omitting the --unstable flag
• Trying to use 'deno init fresh' which doesn't exist

2. Which of the following commands correctly starts the Fresh development server after creating a project?

easy

A. deno run -A --unstable main.ts

B. deno fresh start

C. deno start dev.ts

D. deno run -A --unstable dev.ts

Solution

1. Step 1: Identify the development server file in Fresh projects

   Fresh projects use 'dev.ts' as the entry point to start the development server.

2. Step 2: Match the correct command syntax

   The correct command is 'deno run -A --unstable dev.ts' to run the development server.

3. Final Answer:

   deno run -A --unstable dev.ts -> Option D

4. Quick Check:

   Start Fresh dev server = deno run -A --unstable dev.ts [OK]

Hint: Fresh dev server runs from dev.ts with deno run [OK]

Common Mistakes:

• Trying to run main.ts which does not exist by default
• Using 'deno fresh start' which is not a valid command
• Omitting the -A or --unstable flags

3. After running deno run -A --unstable https://fresh.deno.dev/init myapp and changing into the myapp folder, what will happen if you run deno run -A --unstable dev.ts?

medium

A. Starts the Fresh development server and serves the app at localhost

B. Throws an error because dev.ts does not exist

C. Builds the project but does not start a server

D. Runs tests on the Fresh project

Solution

1. Step 1: Understand the effect of the init command

   The init command creates a new Fresh project folder with all necessary files including dev.ts.

2. Step 2: Running dev.ts starts the development server

   Running 'deno run -A --unstable dev.ts' inside the project folder launches the Fresh dev server, serving the app locally.

3. Final Answer:

   Starts the Fresh development server and serves the app at localhost -> Option A

4. Quick Check:

   Running dev.ts in Fresh project = starts dev server [OK]

Hint: dev.ts runs the server after init creates the project [OK]

Common Mistakes:

• Assuming dev.ts is missing after init
• Thinking dev.ts only builds without serving
• Confusing dev.ts with test scripts

4. You ran deno run -A --unstable https://fresh.deno.dev/init myapp but got an error: error: Cannot resolve module. What is the most likely cause?

medium

A. You have no internet connection to fetch the init script

B. You forgot to include the -A permission flag

C. You ran the command inside an existing Fresh project folder

D. You used an invalid project name with spaces

Solution

1. Step 1: Understand the error meaning

   'Cannot resolve module' means Deno cannot download the script from the URL.

2. Step 2: Identify common causes

   This usually happens if there is no internet connection or the URL is unreachable.

3. Final Answer:

   You have no internet connection to fetch the init script -> Option A

4. Quick Check:

   Module fetch error = no internet connection [OK]

Hint: Check internet if module fetch fails during init [OK]

Common Mistakes:

• Assuming permission flags cause module resolution errors
• Thinking running inside project folder causes this error
• Ignoring invalid project name as cause

5. You want to create a Fresh project named blog and start the development server. Which sequence of commands is correct?

hard

A. deno run -A https://fresh.deno.dev/init blog && cd blog && deno run dev.ts

B. deno fresh init blog && cd blog && deno start dev.ts

C. deno run -A --unstable https://fresh.deno.dev/init blog && cd blog && deno run -A --unstable dev.ts

D. deno create fresh blog && cd blog && deno run -A dev.ts

Solution

1. Step 1: Use the correct Fresh init command

   The correct command to create a Fresh project is 'deno run -A --unstable https://fresh.deno.dev/init blog'.

2. Step 2: Change directory and start the dev server

   After creation, change into the 'blog' folder and run 'deno run -A --unstable dev.ts' to start the server.

3. Final Answer:

   deno run -A --unstable https://fresh.deno.dev/init blog && cd blog && deno run -A --unstable dev.ts -> Option C

4. Quick Check:

   Init + cd + dev.ts run = deno run -A --unstable https://fresh.deno.dev/init blog && cd blog && deno run -A --unstable dev.ts [OK]

Hint: Init with URL, cd, then run dev.ts with flags [OK]

Common Mistakes:

• Using 'deno fresh init' which is invalid
• Omitting --unstable flag
• Not changing directory before running dev.ts