React Naming Conventions Architecture: JSX Element Resolution, Capitalization Rules, and Transpilation Mechanics

React Naming Conventions & JSX Transpilation Architecture

Component capitalization in React isn't just an aesthetic style guide—it is a strict compiler-level requirement enforced during AST parsing and JSX transpilation.

In this engineering guide, we dissect the AST (Abstract Syntax Tree) transformation rules of JSX, examine how Babel and SWC differentiate native DOM elements from user-defined components, and establish best practices for dynamic component selection.

 

---

1. The Mechanical Reason: JSX Transpilation Rules

JSX is an XML-like syntax extension for JavaScript. Because browser JavaScript engines do not natively execute JSX, modern compilers (like Babel, SWC, or ESBuild) must transform JSX elements into standard function calls during build time.

LOWERCASE TAGS

Built-in HTML/DOM

Transpiled as literal strings (e.g., 'div', 'span'). Passed to React.createElement('div') for DOM node creation.

UPPERCASE TAGS

User Components

Transpiled as variable references (e.g., Button). Passed to React.createElement(Button) for component invocation.

DOT NOTATION

Compound Namespaces

Identifiers containing dots (e.g., <Form.Input />) are always parsed as direct variable lookups, regardless of casing.

---

2. Transpilation Output Breakdown

Compare the generated output during build-time transpilation when using lowercase versus uppercase tag identifiers:

Transpilation Comparison: String Literals vs Object Identifiers

// 1. JSX Source Code
const Element = () => (
  <div>
    <button>Click Me</button>      {/* Lowercase: Evaluated as HTML string */}
    <Button>Submit</Button>        {/* Uppercase: Evaluated as JS variable */}
  </div>
);

// 2. Transpiled Output (Modern React JSX Transform: jsx-runtime)
import { jsx as _jsx, jsxs as _jsxs } from 'react/jsx-runtime';

const Element = () => (
  _jsxs('div', {
    children: [
      _jsx('button', { children: 'Click Me' }), // Transpiled as string 'button'
      _jsx(Button, { children: 'Submit' }),     // Transpiled as referenced variable Button
    ],
  })
);

Dynamic Component Resolution Pattern in TypeScript

import React, { ElementType } from 'react';

interface DynamicIconProps {
  iconType: 'user' | 'settings' | 'mail';
}

const iconMap: Record<string, ElementType> = {
  user: UserIcon,
  settings: SettingsIcon,
  mail: MailIcon,
};

export const DynamicIcon = ({ iconType }: DynamicIconProps) => {
  // CORRECT: Reassign to an capitalized variable identifier so JSX parser recognizes it as a component
  const ComponentToRender = iconMap[iconType] ?? DefaultIcon;

  return (
    <div className="icon-wrapper">
      <ComponentToRender className="h-5 w-5" />
    </div>
  );
};

---

3. Identifier Resolution Matrix

Understanding how the JSX compiler categorizes tag names during AST construction:

JSX Tag Syntax	AST Node Classification	Transpiled Expression Type	Execution Behavior
<header />	JSXIdentifier (Lowercase)	String Literal ("header")	Renders DOM <header> node
<Header />	JSXIdentifier (Capitalized)	Identifier Variable Reference (Header)	Invokes Header() function component
<components.header />	JSXMemberExpression	Property Access (components.header)	Invokes object property as component

---

💡 Engineering Takeaways for React Naming Conventions

• Use PascalCase for Component Names: Always name custom components starting with a capital letter (e.g., UserProfile, NavigationMenu) to ensure compiler variable binding.
• Reassign Dynamic Component Names: When passing components as props or mapping from dictionaries, assign the component to a PascalCase variable before rendering in JSX.
• Dot Notation Bypass: You can bypass the PascalCase requirement by using namespace objects (e.g., <ui.button />), though PascalCase remains the industry standard for readability.

Understanding JSX transpilation mechanics helps prevent common runtime errors and keeps your code scalable.

Happy Engineering! 🚀