Does Nutlope/Hallmark Have a `src` or `lib` Directory? Project Structure Explained

The Hallmark repository does not contain a top-level src or lib directory—its source files live in site/ for static assets and skills/hallmark/ for Markdown documentation.

Hallmark is a static-site and design-skill project where the conventional roles of src and lib are already handled by existing folders. This guide explains the current repository layout, why those directories are absent, and how they would fit if added in future iterations.

Current Repository Structure

The Hallmark project organizes code across two primary locations instead of a traditional src/lib split:

• site/ — Contains HTML, CSS, and JavaScript files that power the live demos and landing pages. Examples include site/index.html and site/examples/tally/app.js.
• skills/hallmark/ — Houses Markdown-based reference material, including SKILL.md, which drives the site's content layer.

This structure reflects a static-site architecture where assets are served directly without a compilation step. The hosting platform (Vercel) handles deployment without requiring bundled output directories.

Why src and lib Are Absent

In typical JavaScript/TypeScript projects, these directories serve distinct purposes that Hallmark currently fulfills elsewhere:

Directory	Conventional Purpose	Hallmark Equivalent
src	Source code written by developers (components, utilities, TypeScript files)	site/ — raw HTML/JS files loaded directly
lib	Compiled bundles, distribution files, or vendored dependencies	Not needed — no build pipeline produces compiled artifacts

All JavaScript in Hallmark executes as native browser modules. For example, site/examples/tally/app.js contains application logic that runs without transpilation or bundling.

How src or lib Would Fit in Hallmark

If the project expands to include reusable components or a build process, these directories would slot into the architecture as follows:

Adding a src Directory

A src/ folder would become the home for authorable source code—TypeScript utilities, shared components, or configuration files that require compilation before deployment.

// src/utils.js
export function formatCurrency(value) {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
  }).format(value);
}

Static pages in site/ would then import from this source tree using ES modules:

<!-- site/examples/custom-03/index.html -->
<script type="module">
  import { formatCurrency } from '../../src/utils.js';
  document.getElementById('price').textContent = formatCurrency(1999);
</script>

Adding a lib Directory

A lib/ directory would store build artifacts—the compiled output of any bundler (esbuild, Vite, Rollup) that processes src/ files. The static HTML would reference these optimized bundles instead of raw source:

<!-- Production-ready reference -->
<script src="../../lib/utils.bundle.js"></script>

This separation matters for caching strategies, tree-shaking, and dependency management at scale.

Key Files Demonstrating the Current Approach

Three files illustrate why Hallmark operates without src or lib:

• README.md — Documents the project layout and confirms the static-site philosophy.
• site/index.html — Loads scripts directly from relative paths like examples/tally/app.js rather than compiled bundles.
• skills/hallmark/SKILL.md — Serves as the content source, parsed and displayed without intermediate processing.

Summary

• Hallmark currently has no src or lib directory at the repository root.
• The site/ folder handles raw source assets; skills/hallmark/ manages Markdown content.
• These conventional folders would only appear if Hallmark adds a compilation layer or reusable component library.
• Existing JavaScript runs in browsers as-is, with Vercel handling deployment.

Frequently Asked Questions

What would happen if I added a src directory to Hallmark?

You could write modular JavaScript or TypeScript utilities and import them into pages under site/. You would likely need to configure a bundler (Vite, esbuild) to produce browser-compatible output, potentially placing results in lib/ or dist/.

Does Hallmark use any build tools currently?

No. The repository relies on static file serving and native ES modules where needed. There is no package.json build script or compilation step referenced in the project structure.

Why do some projects need lib if src already exists?

src/ contains human-readable source code that often uses modern syntax or TypeScript, requiring transpilation. lib/ (or dist/) holds machine-optimized output suitable for browsers and npm publication—minified, polyfilled, and dependency-resolved.

Would adding src improve Hallmark's architecture?

Only if the project grows beyond simple demos. Current static files in site/ are sufficient for the design-skill showcase. A src/ layer becomes valuable when introducing shared components across multiple examples or adding type safety through TypeScript.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}