From 2baf8cb17a5f665f7b050d07bd4f263a6f6c725b Mon Sep 17 00:00:00 2001 From: Kyle June Date: Mon, 2 Sep 2024 18:30:09 -0400 Subject: [PATCH] Start work on configuration guide --- docs/configuration.md | 115 ++++++++++++++++++++++++++++++++++++---- docs/getting-started.md | 6 ++- docs/routing.md | 6 ++- 3 files changed, 113 insertions(+), 14 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 92645d7..4cdec9c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,14 +1,13 @@ # Configuration -TODO: Make an outline then fill it in with details. +This guide covers the configuration options available for your project. - [Configuration](#configuration) - [Tasks](#tasks) - [Compiler options](#compiler-options) - - [Linting](#linting) - - [Formatting](#formatting) + - [Formatting and linting](#formatting-and-linting) - [Imports](#imports) - - [Application](#application) + - [Server](#server) - [Build](#build) - [esbuild](#esbuild) - [Development](#development) @@ -17,7 +16,8 @@ TODO: Make an outline then fill it in with details. ## Tasks To learn more about using the default tasks, see the -[tasks](getting-started.md#tasks) section in the getting started guide. +[tasks](getting-started.md#tasks) section in the getting started guide. Each +task has a description of what it does in a comment above the task declaration. If you need to customize your build options to be different from the default, follow the instructions for adding the [build.ts](getting-started.md#buildts) @@ -35,13 +35,107 @@ workflows, you may need to modify them to use different tasks. See the ## Compiler options -## Linting - -## Formatting +The default compiler options from the +[getting started guide](getting-started.md#denojsonc) should be sufficient for +most use cases. If you need to customize them, you can do so by modifying the +`compilerOptions` in the `deno.jsonc` file. + +```json +{ + "compilerOptions": { + "lib": ["esnext", "dom", "dom.iterable", "dom.asynciterable", "deno.ns"], + "jsx": "react-jsx", + "jsxImportSource": "react", + "jsxImportSourceTypes": "@types/react" + } +} +``` + +For more information about the available options, see Deno's +[configuring TypeScript in Deno guide](https://docs.deno.com/runtime/manual/advanced/typescript/configuration/). + +## Formatting and linting + +You can configure Deno's formatter and linter to include or ignore files or +directories by adding the fmt or lint key to your configuration. Alternatively, +if you only want to exclude the same files or directories for both, you can +update the top level excludes array. Below is the default excludes array from +the [getting started guide](getting-started.md#denojsonc). It ensures that the +formatter ignores coverage report json files, your npm dependencies stored in +the node_modules directory, and the build artifacts from this framework. + +```json +{ + "exclude": [ + "coverage", + "node_modules", + "public/build", + "routes/_main.ts", + "routes/_main.tsx" + ] +} +``` ## Imports -## Application +The imports section of the `deno.jsonc` file is used to configure an import map +for resolving bare specifiers. It makes it so that you don't have to specify the +version everywhere that your dependency is used and provides one centralized +place for updating those versions. + +For example, if your import map has the entry `"react": "npm:react@18.3.1"`, +you'll be able to import react like `import React from "react"` and it will +resolve to `npm:react@18.3.1`. + +The default import map from the +[getting started guide](getting-started.md#denojsonc) also has 2 entries in it +that make it easy to import files relative to the root of your project. Instead +of having to import files with a path relative to the current file, you can +import them with a path relative to the root of your project. For example, if +you have your shared components in the components directory, you can import them +like `import Button from "/components/Button.tsx"` instead of +`import Button from "../../components/Button.tsx"`. + +```json +{ + "imports": { + "/": "./", + "./": "./" + } +} +``` + +For more information about import maps, see Deno's +[import map](https://docs.deno.com/runtime/manual/basics/import_maps/) +documentation. + +## Server + +In all of the examples, the main entry point for the application is the +`main.ts` or `main.tsx` file. This is the file that is used to start the +application and contains the configuration for starting it. For most +applications, you can just use the serve function to start your application. If +a port is not specified, the operating system will choose an available port +automatically. The route and router options come from geenerated build +artifacts. The working directory is the directory that contains the main entry +point file. The configuration for logging is stored in the `log.ts` file, for +more information about configuring logging, see the [logging](logging.md) guide. + +```ts +import * as path from "@std/path"; +import { serve } from "@udibo/react-app/server"; + +import route from "./routes/_main.tsx"; +import router from "./routes/_main.ts"; +import "./log.ts"; + +await serve({ + port: 9000, + router, + route, + workingDirectory: path.dirname(path.fromFileUrl(import.meta.url)), +}); +``` ## Build @@ -55,4 +149,5 @@ using common styling plugins for esbuild. ## Environment variables TODO: Cover the basics of environment variables, with a focus on how to use -dotfiles for development, production, and test environment variables. +dotfiles for development, production, and test environment variables. Update +tasks to use dotfiles. diff --git a/docs/getting-started.md b/docs/getting-started.md index 9987ca3..1da39ae 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -684,11 +684,13 @@ comprehensive [error handling guide](./error-handling.md). ## Metadata Metadata is crucial for improving SEO, social media sharing, and overall user -experience in your application. +experience in your application. It is also where you can add scripts and styles +to your application. For detailed information on implementing and managing metadata, including best practices and advanced techniques, please refer to our -[Metadata guide](./metadata.md). +[Metadata guide](./metadata.md). For more information on how to style your +application, please refer to the [Styling guide](./styling.md). ## Logging diff --git a/docs/routing.md b/docs/routing.md index 23f2498..94d0669 100644 --- a/docs/routing.md +++ b/docs/routing.md @@ -809,8 +809,10 @@ comprehensive [Error handling guide](./error-handling.md). ## Metadata Metadata is crucial for improving SEO, social media sharing, and overall user -experience in your application. +experience in your application. It is also where you can add scripts and styles +to your application. For detailed information on implementing and managing metadata, including best practices and advanced techniques, please refer to our -[Metadata guide](./metadata.md). +[Metadata guide](./metadata.md). For more information on how to style your +application, please refer to the [Styling guide](./styling.md).