Adding New JavaScript Components
Relevant source files
The following files were used as context for generating this wiki page:
Within the Docker documentation project, new JavaScript components are primarily added in the context of creating educational guides. These guides demonstrate how to use Docker with various JavaScript technologies. The implementation of JS components generally follows two main patterns: simple, single-page applications with direct script inclusions, or more complex, multi-service applications that are fully containerized.
This document outlines these two architectural patterns, the development workflow for contributing new JS-based guides, and the best practices as defined within the repository's contribution guidelines. The focus is on providing practical, hands-on experience through step-by-step tutorials.
Sources: content/contribute/guides.md:11-13
Architectural Patterns for JS Components
There are two primary methods for integrating JavaScript components into the documentation guides: direct script inclusion for self-contained examples and containerized environments for full-stack applications.
Pattern 1: Direct Script Inclusion
This pattern is used for simple, client-side focused guides, such as the TensorFlow.js face detection example. The application is a single HTML page that directly includes necessary JavaScript libraries and custom logic files via <script> tags. This approach is suitable for demonstrating a specific technology without the overhead of a full build system.
Sources: content/guides/tensorflowjs.md
Key Characteristics
- Structure: A main
index.htmlfile serves as the application's entry point. - Dependencies: JavaScript libraries are loaded directly from CDNs or local files using
<script>tags. - Logic: Custom application logic is contained in a separate JavaScript file (e.g.,
index.js) and also included via a<script>tag. - Deployment: The entire application is served as static content, typically using a simple web server like Nginx within a Docker container.
Sources: content/guides/tensorflowjs.md:104-120, 260-263
The diagram below illustrates the architecture of the TensorFlow.js example.
Example: TensorFlow.js Face Detection Guide
The face detection guide uses this pattern to demonstrate a machine learning model running in the browser.
- HTML Structure: The
index.htmlfile sets up the video and canvas elements for display. - JS Libraries: It includes several TensorFlow.js libraries for core functionality, different computation backends (WASM, WebGL, CPU), and the BlazeFace model for face detection.
- Application Logic: The
index.jsfile contains the logic to set up the camera, load the model, and render predictions in a loop usingrequestAnimationFrame.
The following table lists the external scripts loaded in the TensorFlow.js example.
| Library/Script | Purpose |
|---|---|
tf-core.js | Core TensorFlow.js functionality. |
tf-converter.js | For model conversion. |
tf-backend-webgl.js | WebGL backend for GPU-accelerated computation. |
tf-backend-cpu.js | CPU backend as a fallback. |
tf-backend-wasm.js | WebAssembly backend for near-native performance. |
blazeface.js | The pre-trained BlazeFace model for face detection. |
dat.gui.min.js | A GUI for changing settings like the computation backend. |
Stats.min.js | Displays performance metrics like FPS. |
index.js | Custom logic for camera setup, prediction rendering, and UI control. |
Sources: content/guides/tensorflowjs.md:112-120, 131-163
Pattern 2: Containerized Full-Stack Applications
For more complex guides involving both frontend and backend JavaScript components (e.g., Node.js and React.js), a containerized, multi-service architecture is used. Each part of the application (frontend, backend, database) runs in its own container, orchestrated by Docker Compose.
Sources: content/get-started/introduction/develop-with-containers.md:29-45, content/guides/nodejs/_index.md:10-14, content/guides/reactjs/_index.md:10-14
Key Characteristics
- Structure: A multi-container setup defined in a
docker-compose.yamlfile. - Services: Separate containers for the frontend (e.g., React dev server), backend (e.g., Node.js API), database (e.g., MySQL/PostgreSQL), and a reverse proxy.
- Development: The
docker compose watchcommand is used to enable a fast feedback loop with hot-reloading for both frontend and backend code. - Proxy: A proxy like Traefik is used to route requests to the appropriate service based on the URL path, allowing all services to be accessed through a single port.
Sources: content/get-started/introduction/develop-with-containers.md:38-45, CONTRIBUTING.md:65-69
The diagram below shows the service architecture for the "Develop with Containers" guide.
Example: Node.js To-Do Application
The "Develop with Containers" guide uses a to-do application to illustrate this pattern. The environment consists of several services:
| Service | Container Image/Technology | Purpose |
|---|---|---|
| React Frontend | Node with Vite | Serves the user interface and handles client-side logic. |
| Node Backend | Node | Provides a REST API for managing to-do items. |
| Database | MySQL | Persists the to-do list items. |
| DB Admin | phpMyAdmin | Provides a web-based interface to interact with the database. |
| Proxy | Traefik | Routes incoming HTTP requests to the correct containerized service. |
Sources: content/get-started/introduction/develop-with-containers.md:38-45
The backend Node.js service is containerized using a Dockerfile. A typical Dockerfile for a Node.js application includes steps to select a base image, set a working directory, copy dependencies, install them, copy source code, and define the startup command.
Sources: content/get-started/docker-concepts/building-images/writing-a-dockerfile.md:10-25, 90-98
Contribution and Development Workflow
Adding a new guide with JavaScript components follows a standard contribution process for the repository.
Local Development
The recommended local development setup uses Docker Compose to build and serve the documentation site. The docker compose watch command starts a development server that automatically rebuilds the site upon file changes. This is also the same command used for developing the sample applications within the guides themselves, providing a consistent developer experience.
Sources: CONTRIBUTING.md:54-73, content/get-started/introduction/develop-with-containers.md:29-31
The following flowchart outlines the local development and contribution process for a new guide.
Example Code Repositories
For guides that include sample application code, it is strongly encouraged to publish the code in a repository under the dockersamples GitHub organization. This ensures the code remains accessible and maintainable by the documentation team. Contributors can initiate a sample repository using the dockersamples/sample-app-template and request a transfer upon submitting their documentation pull request.
Sources: content/contribute/guides.md:94-108
Conclusion
Adding new JavaScript components to the Docker documentation is accomplished by creating new usage guides. These guides employ one of two main architectural patterns: simple, static HTML with direct script includes for client-side examples, or complex, multi-container applications for full-stack demonstrations. The contribution process is standardized, leveraging docker compose watch for local development and encouraging the use of the dockersamples organization for hosting example code, ensuring consistency and maintainability across all documentation.
Sources: content/contribute/guides.md:11-13, 94-97, CONTRIBUTING.md:65-69