Step 1 of 4

Introduction to Antigravity and Project Structure

Chapter 1: Introduction to Antigravity and Project Structure

Welcome to the foundational chapter of our journey. Before we write a single line of code for our e-commerce store, we must first understand the engine that will power it: the Antigravity framework. This chapter will demystify what Antigravity is, why it's an excellent choice for modern web applications, and how to architect a professional, scalable project from the ground up. We will move beyond superficial setup and delve into the philosophy and structure that will support a complex, real-world application.

What is Antigravity?

Antigravity is not just another JavaScript library; it is a progressive, component-based framework designed for building dynamic user interfaces with a declarative syntax. Think of it as a system that allows you to describe what your UI should look like for any given state, and Antigravity takes care of efficiently updating and rendering the components when that state changes. This is a paradigm shift from imperatively manipulating the DOM.

Its core principles include a virtual DOM for efficient updates, a reactive state management system, and a component-based architecture that promotes reusability and separation of concerns. For an e-commerce store, this means we can build independent components for a product card, shopping cart item, or user review, and compose them together to form complex pages that remain performant and easy to maintain.

Note: The Virtual DOM Explained

When you change the state of a component in Antigravity, it doesn't directly update the real browser DOM. Instead, it updates a lightweight JavaScript object representation—the Virtual DOM. Antigravity then compares (diffs) this new Virtual DOM with the previous snapshot and calculates the most efficient way to apply those minimal changes to the actual DOM. This process, called reconciliation, is key to Antigravity's performance, especially in frequently updating interfaces like a live shopping cart.

Initializing the Project: Beyond `create-antigravity-app`

We will use the official project scaffolding tool. Open your terminal and run:


npx create-antigravity-app antigravity-store --template typescript
cd antigravity-store
npm install

This command does several critical things: it creates a new directory named `antigravity-store`, sets up a pre-configured build pipeline (using Vite or a similar bundler), installs Antigravity's core library and its necessary dependencies, and configures a TypeScript environment for type safety. The `--template typescript` flag is non-negotiable for a serious project; it will save countless hours by catching errors during development rather than at runtime.

Pro Tip: Package Manager Choice

While we use `npm` here, you can use `yarn` or `pnpm` interchangeably (`yarn create antigravity-app...`). `pnpm` is highly recommended for its superior disk space efficiency and speed, especially as your project grows with many dependencies.

Anatomy of the Generated Project Structure

Let's dissect the generated folder structure. Understanding the purpose of each file is crucial for knowing where to place our future code.


antigravity-store/
├── node_modules/          # All project dependencies (never edit manually)
├── public/                # Static assets (images, favicon, robots.txt)
│   └── vite.svg
├── src/                   # The heart of our application
│   ├── assets/            # Dynamic assets like CSS, SCSS, fonts
│   ├── components/        # Reusable UI components (Button, Card, etc.)
│   │   └── HelloWorld.ag  # Example component
│   ├── pages/             # Page-level components (Home, ProductListing)
│   ├── layouts/           # Wrapper components for common page structures
│   ├── stores/            # State management (using Pinia or similar)
│   ├── routers/           # Application routing definitions
│   ├── utils/             # Helper functions, constants, formatters
│   ├── types/             # Global TypeScript interfaces and types
│   ├── main.ts            # Application entry point
│   ├── App.ag             # The root application component
│   └── style.css          # Global styles
├── index.html             # The single HTML page that hosts the app
├── package.json           # Project metadata and dependency list
├── tsconfig.json          # TypeScript compiler configuration
├── vite.config.ts         # Build tool configuration (Vite)
└── README.md

This structure enforces a clear separation of concerns. The `src/components` directory is for dumb, presentational components. The `src/pages` directory is for smart components that fetch data and compose other components. The `src/stores` directory is where we will manage global state, such as the user's shopping cart and authentication status, ensuring data is consistent across all components.

Warning: Don't Pollute the Root

Avoid creating many files in the `src/` root. Placing a `ProductCard` component directly in `src/` might seem convenient now, but it will lead to an unmaintainable "spaghetti" directory as the project scales to hundreds of files. Adhere to the folder structure religiously from day one.

Your First Antigravity Component: A Deep Dive

Let's examine and rewrite the default `App.ag` component to understand the syntax. We'll transform it into a simple store header.

// File: src/App.ag
import { reactive } from 'antigravity';
import './style.css';
import StoreHeader from './components/StoreHeader.ag';

function App() {
  // Reactive state: when 'storeName' changes, the UI updates automatically.
  const state = reactive({
    storeName: 'Antigravity Emporium',
    tagline: 'Defying ordinary shopping since 2023'
  });

  // The template returned by the component function.
  return `
    
      
      <${StoreHeader} name="${state.storeName}" tagline="${state.tagline}" />

      
        Welcome to ${state.storeName}
        ${state.tagline}. Our store is currently under construction.
        
      
    
  `;
}

export default App;

Let's break this down line