TypeScript compatibility (#379)

* Update file extensions and exports for TypeScript compatibility

* docs: fix typo in getting-started.md

* chore: add no-trailing-punctuation rule to VS Code settings

* feat: add @docusaurus/theme-mermaid for mermaid diagram support

* Update import paths for MermaidDiagram component

* remove redudndant check, use effect only runs after the component is mounted

* Update docusaurus.config.ts to fix syntax error

* bring back check because it's not possible to properly cancel a dynamic import

* feat: optimize dynamic import in CodeBlock component

* chore: update VS Code extensions.json with eslint recommendation

* Update docusaurus.config.ts to add GitHub repository link in header

.gitignore

@@ -1,6 +1,20 @@
-node_modules/
-build/
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
 .docusaurus
 .cache-loader
-Cargo.lock
-yarn.lock
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

.vscode/extensions.json

@@ -2,6 +2,7 @@
   "recommendations": [
     "esbenp.prettier-vscode",
     "davidanson.vscode-markdownlint",
-    "unifiedjs.vscode-mdx"
+    "unifiedjs.vscode-mdx",
+    "dbaeumer.vscode-eslint"
   ]
 }

.vscode/settings.json

@@ -4,6 +4,9 @@
     "no-inline-html": false,
     "link-image-reference-definitions": false,
     "commands-show-output": false,
-    "fenced-code-language": false
+    "fenced-code-language": false,
+    "no-trailing-punctuation": {
+      "punctuation": ".,;:。，；："
+    }
   }
 }

docs/conn_lifecycle.md

@@ -2,6 +2,12 @@
 title: Connection Lifecycle
 ---
 
+import MermaidDiagram from "@site/src/components/mermaid_diagram";
+import connection_overview from '!!raw-loader!@site/static/img/diagrams/connection_overview.mmd';
+import connection_accept from '!!raw-loader!@site/static/img/diagrams/connection_accept.mmd';
+import connection_worker from '!!raw-loader!@site/static/img/diagrams/connection_worker.mmd';
+import connection_request from '!!raw-loader!@site/static/img/diagrams/connection_request.mmd';
+
 # Architecture overview
 
 After Server has started listening to all sockets, [`Accept`][accept] and [`Worker`][worker] are two main loops responsible for processing incoming client connections.
@@ -10,23 +16,23 @@ Once connection accepted Application level protocol processing happens in a prot
 
     Please note, below diagrams are outlining happy-path scenarios only.
 
-![Connection Overview](/img/diagrams/connection_overview.svg)
+<MermaidDiagram value={connection_overview}  />
 
 ## Accept loop in more detail
 
-![Connection Accept](/img/diagrams/connection_accept.svg "Connection Accept")
+<MermaidDiagram value={connection_accept}  />
 
 Most of code implementation resides in [`actix-server`][server] crate for struct [`Accept`][accept].
 
 ## Worker loop in more detail
 
-![Connection Worker](/img/diagrams/connection_worker.svg "Connection Worker")
+<MermaidDiagram value={connection_worker}  />
 
 Most of code implementation resides in [`actix-server`][server] crate for struct [`Worker`][worker].
 
 ## Request loop roughly
 
-![Connection Request](/img/diagrams/connection_request.svg "Connection Request")
+<MermaidDiagram value={connection_request}  />
 
 Most of code implementation for request loop resides in [`actix-web`][web] and [`actix-http`][http] crates.
 

docs/getting-started.md

@@ -2,14 +2,16 @@
 title: Getting Started
 ---
 
-import RenderCodeBlock from '@theme/CodeBlock'; import CodeBlock from "@site/src/components/code_block"; import { rustVersion, actixWebMajorVersion } from "@site/vars";
+import RenderCodeBlock from '@theme/CodeBlock';
+import CodeBlock from "@site/src/components/code_block";
+import vars from "@site/vars";
 
 ## Installing Rust
 
 If you don't have Rust yet, we recommend you use `rustup` to manage your Rust installation. The [official rust guide][rustguide] has a wonderful section on getting started.
 
 <p>
-Actix Web currently has a minimum supported Rust version (MSRV) of { rustVersion }. Running <code>rustup update</code> will ensure you have the latest and greatest Rust version available. As such, this guide assumes you are running Rust { rustVersion } or later.
+Actix Web currently has a minimum supported Rust version (MSRV) of { vars.rustVersion }. Running <code>rustup update</code> will ensure you have the latest and greatest Rust version available. As such, this guide assumes you are running Rust { vars.rustVersion } or later.
 </p>
 
 ## Hello, world!
@@ -27,7 +29,7 @@ Add `actix-web` as a dependency of your project by adding the following to your
 
 <RenderCodeBlock className="language-toml">
 {`[dependencies]
-actix-web = "${actixWebMajorVersion}"`}
+actix-web = "${vars.actixWebMajorVersion}"`}
 </RenderCodeBlock>
 
 Request handlers use async functions that accept zero or more parameters. These parameters can be extracted from a request (see `FromRequest` trait) and returns a type that can be converted into an `HttpResponse` (see `Responder` trait):

docs/http2.md

@@ -2,7 +2,8 @@
 title: HTTP/2
 ---
 
-import RenderCodeBlock from '@theme/CodeBlock'; import CodeBlock from '@site/src/components/code_block'; import { actixWebMajorVersion } from "@site/vars";
+import RenderCodeBlock from '@theme/CodeBlock';
+import CodeBlock from '@site/src/components/code_block';
 
 `actix-web` automatically upgrades connections to _HTTP/2_ if possible.
 

docs/http_server_init.md

@@ -2,6 +2,10 @@
 title: HTTP Server Initialization
 ---
 
+import CodeBlock from "@site/src/components/code_block";
+import MermaidDiagram from "@site/src/components/mermaid_diagram";
+import http_server from '!!raw-loader!@site/static/img/diagrams/http_server.mmd';
+
 # Architecture overview
 
 Below is a diagram of HttpServer initialization, which happens on the following code
@@ -19,4 +23,4 @@ async fn main() -> std::io::Result<()> {
 }
 ```
 
-![HTTP Server Diagram](/img/diagrams/http_server.svg)
+<MermaidDiagram value={http_server}  />

docs/server.md

@@ -2,7 +2,9 @@
 title: Server
 ---
 
-import RenderCodeBlock from '@theme/CodeBlock'; import CodeBlock from '@site/src/components/code_block'; import { actixWebMajorVersion } from "@site/vars";
+import RenderCodeBlock from '@theme/CodeBlock';
+import CodeBlock from '@site/src/components/code_block';
+import vars from "@site/vars";
 
 # The HTTP Server
 
@@ -60,7 +62,7 @@ The `rustls` crate feature is for `rustls` integration and `openssl` is for `ope
 
 <RenderCodeBlock className="language-toml">
 {`[dependencies]
-actix-web = { version = "${actixWebMajorVersion}", features = ["openssl"] }
+actix-web = { version = "${vars.actixWebMajorVersion}", features = ["openssl"] }
 openssl = { version = "0.10" }
 `}
 </RenderCodeBlock>

docs/whatis.md

@@ -2,7 +2,7 @@
 title: What is Actix Web
 ---
 
-import { rustVersion } from "@site/vars";
+import vars from "@site/vars";
 
 # Actix Web is part of an Ecosystem of Crates
 
@@ -16,7 +16,7 @@ We call Actix Web a powerful and pragmatic framework. For all intents and purpos
 An application developed with Actix Web will expose an HTTP server contained within a native executable. You can either put this behind another HTTP server like nginx or serve it up as-is. Even in the complete absence of another HTTP server, Actix Web is powerful enough to provide HTTP/1 and HTTP/2 support as well as TLS (HTTPS). This makes it useful for building small services ready for production.
 
 <p>
-Most importantly: Actix Web runs on Rust { rustVersion } or later and it works with stable releases.
+Most importantly: Actix Web runs on Rust { vars.rustVersion } or later and it works with stable releases.
 </p>
 
 <!-- TODO -->

docusaurus.config.ts

@@ -1,9 +1,11 @@
-const path = require("path");
-const {
-  themes: { dracula: draculaTheme },
-} = require("prism-react-renderer");
+import { Config } from "@docusaurus/types";
+import type * as Preset from "@docusaurus/preset-classic";
 
-module.exports = {
+import { themes as prismThemes } from "prism-react-renderer";
+
+const draculaTheme = prismThemes.dracula;
+
+const config: Config = {
   title: "Actix",
   tagline:
     "Actix Web is a powerful, pragmatic, and extremely fast web framework for Rust",
@@ -14,6 +16,12 @@ module.exports = {
   favicon: "img/logo.png",
   organizationName: "actix", // Usually your GitHub org/user name.
   projectName: "actix-web", // Usually your repo name.
+  // https://docusaurus.io/docs/api/themes/@docusaurus/theme-mermaid
+  // https://docusaurus.io/docs/markdown-features/diagrams
+  markdown: {
+    mermaid: true,
+  },
+  themes: ["@docusaurus/theme-mermaid"],
   themeConfig: {
     navbar: {
       title: "Actix",
@@ -42,6 +50,12 @@ module.exports = {
           label: "Code",
           position: "left",
         },
+        {
+          href: "https://github.com/actix/actix-web",
+          position: "right",
+          className: "header-github-link",
+          "aria-label": "GitHub repository",
+        },
       ],
     },
     footer: {
@@ -56,14 +70,14 @@ module.exports = {
     colorMode: {
       respectPrefersColorScheme: true,
     },
-  },
+  } satisfies Preset.ThemeConfig,
   plugins: [
     "docusaurus-plugin-sass",
     require.resolve("docusaurus-lunr-search"),
   ],
   presets: [
     [
-      "@docusaurus/preset-classic",
+      "classic",
       {
         docs: {
           sidebarPath: require.resolve("./sidebars.js"),
@@ -72,7 +86,9 @@ module.exports = {
         theme: {
           customCss: require.resolve("./src/css/custom.css"),
         },
-      },
+      } satisfies Preset.Options,
     ],
   ],
 };
+
+export default config;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "actix-website",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -16,6 +16,7 @@
   "dependencies": {
     "@docusaurus/core": "^3.3.2",
     "@docusaurus/preset-classic": "^3.3.2",
+    "@docusaurus/theme-mermaid": "^3.3.2",
     "@fortawesome/fontawesome-svg-core": "^6.5.0",
     "@fortawesome/free-solid-svg-icons": "^6.5.0",
     "@fortawesome/react-fontawesome": "^0.2",
@@ -26,12 +27,15 @@
     "prism-react-renderer": "^2.3.0",
     "react": "^18.0.2",
     "react-dom": "^18.0.2",
-    "sass": "^1.71.0"
+    "sass": "^1.71.0",
+    "usehooks-ts": "^3.1.0"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "^3.3.2",
+    "@docusaurus/tsconfig": "^3.3.2",
     "@docusaurus/types": "^3.3.2",
-    "raw-loader": "^4.0.2"
+    "raw-loader": "^4.0.2",
+    "typescript": "^5.4.5"
   },
   "browserslist": {
     "production": [

sidebars.ts

@@ -1,4 +1,6 @@
-module.exports = {
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+const sidebars: SidebarsConfig = {
   docs: {
     Introduction: ["welcome", "whatis"],
     Basics: [
@@ -43,3 +45,5 @@ module.exports = {
     ],
   },
 };
+
+export default sidebars;

src/components/code_block.tsx

@@ -1,31 +1,38 @@
 import React, { useState, useEffect } from "react";
 import RenderCodeBlock from "@theme/CodeBlock";
+import { useIsMounted } from "usehooks-ts";
 
-const CodeBlock = ({ example, file, section, language }) => {
+type Props = {
+  example: string;
+  file?: string;
+  section: string;
+  language?: string;
+};
+
+const CodeBlock = ({ example, file, section, language }: Props) => {
+  const isMounted = useIsMounted();
   const [code, setCode] = useState("");
 
   useEffect(() => {
-    let isMounted = true;
-
     const path =
       file === "manifest" ? "Cargo.toml" : `src/${file ?? "main.rs"}`;
 
     import(`!!raw-loader!@site/examples/${example}/${path}`)
       .then((source) => {
+        if (!isMounted()) {
+          return;
+        }
+
         source = source.default.match(
           new RegExp(
-            `(?:\/\/|#) <${section}>\n([\\s\\S]*)(?:\/\/|#) <\/${section}>`,
-          ),
+            `(?:\/\/|#) <${section}>\n([\\s\\S]*)(?:\/\/|#) <\/${section}>`
+          )
         )[1];
 
-        if (isMounted) setCode(source);
+        setCode(source);
       })
       .catch((err) => console.log(err));
-
-    return () => {
-      isMounted = false;
-    };
-  }, []);
+  }, [isMounted]);
 
   return (
     <RenderCodeBlock className={`language-${language ?? "rust"}`}>

src/components/mermaid_diagram.tsx

@@ -0,0 +1,12 @@
+import Mermaid from "@theme/Mermaid";
+import React from "react";
+
+type Props = {
+  value: string;
+};
+
+const MermaidDiagram = ({ value }: Props) => {
+  return <Mermaid value={value} />;
+};
+
+export default MermaidDiagram;

src/components/shell_block.jsx

@@ -1,11 +0,0 @@
-import RenderCodeBlock from "@theme/CodeBlock";
-
-const ShellBlock = ({ children }) => {
-  return (
-    <RenderCodeBlock className={`language-console`}>
-      {children}
-    </RenderCodeBlock>
-  );
-};
-
-export default ShellBlock;

src/components/shell_block.tsx

@@ -0,0 +1,14 @@
+import RenderCodeBlock from "@theme/CodeBlock";
+import React from "react";
+
+type Props = {
+  children: React.ReactNode;
+};
+
+const ShellBlock = ({ children }: Props) => {
+  return (
+    <RenderCodeBlock className={`language-console`}>{children}</RenderCodeBlock>
+  );
+};
+
+export default ShellBlock;

src/css/custom.css

@@ -50,3 +50,18 @@ html[data-theme="dark"] {
 .navbar__logo {
   filter: var(--logo-filter);
 }
+
+.header-github-link::before {
+  content: "";
+  width: 24px;
+  height: 24px;
+  display: flex;
+  background-color: var(--ifm-navbar-link-color);
+  mask-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E");
+  transition: background-color var(--ifm-transition-fast)
+    var(--ifm-transition-timing-default);
+}
+
+.header-github-link:hover::before {
+  background-color: var(--ifm-navbar-link-hover-color);
+}

src/plugin.js

@@ -1,11 +0,0 @@
-module.exports = function (context, options) {
-  return {
-    configureWebpack(config, isServer, utils) {
-      return {
-        module: {
-          rules: [{ test: /\.rs$/, use: "raw-loader" }],
-        },
-      };
-    },
-  };
-};

tsconfig.json

@@ -0,0 +1,17 @@
+// https://docusaurus.io/docs/typescript-support
+// This file is not used in compilation. It is here just for a nice editor experience.
+{
+  "extends": "@docusaurus/tsconfig",
+  "compilerOptions": {
+    "baseUrl": ".",
+    // https://miyoon.medium.com/array-parameters-in-tsconfig-json-are-always-overwritten-11c80bb514e1
+    // https://github.com/microsoft/TypeScript/issues/20110
+    "types": [
+      "node",
+      "@docusaurus/module-type-aliases",
+      "@docusaurus/theme-classic",
+      "docusaurus-plugin-sass"
+    ]
+  },
+  "exclude": ["node_modules", "build", ".docusaurus"]
+}

vars.ts

@@ -1,5 +1,7 @@
-module.exports = {
+const vars = {
   rustVersion: "1.72",
   actixWebMajorVersion: "4",
   tokioMajorVersion: "1",
 };
+
+export default vars;