budget-manager/frontend/newbie-tour.md

Vue.js for React Developers: A Guided Tour

Welcome to the LuPa Plant Manager Cockpit's Vue.js frontend! This guide is designed for developers familiar with React who are new to Vue.js. We'll explore the key concepts, syntax differences, and mental models needed to understand and work with this codebase.

Table of Contents

1. Project Structure
2. Component System
3. Reactivity & State Management
4. Template Syntax vs JSX
5. Routing
6. Lifecycle Hooks
7. Styling & UI Components
8. Additional Resources

Project Structure

The Vue project structure is similar to React with some key differences:

frontend-vue/
├── src/                    # Source code directory (same as React)
│   ├── App.vue             # Root component (like App.jsx in React)
│   ├── main.ts             # Application entry point (like index.js)
│   ├── components/         # Reusable components (similar to React)
│   │   └── ui/             # UI component library (similar to shadcn/ui in React)
│   ├── pages/              # Page components (similar to pages/ in Next.js)
│   └── stores/             # State management (similar to Redux or Context)
├── styles/                 # Global styles
└── public/                 # Static assets (same as React)

The main difference: Vue uses Single File Components (SFC) with .vue extension that contain template, script, and style in one file, versus separate .jsx/.tsx and .css files in React.

Component System

Single File Components

Vue's Single File Components (SFCs) combine template, script, and style in one .vue file:

<template>
  <!-- HTML template (like JSX in React) -->
</template>

<script setup>
  // Component logic (like function body in React)
</script>

<style>
  /* Component styles (like CSS modules or styled-components) */
</style>

The closest React equivalent would be combining JSX with CSS modules or styled-components.

Example Components

Explore our commented examples:

• App.vue - Root component with router setup
• PageLayout.vue - Layout component with responsive behavior
• Navigation.vue - Navigation component with router links

Component Composition

Vue components can be composed similarly to React:

<template>
  <PageLayout>
    <Card>
      <CardContent> Hello world! </CardContent>
    </Card>
  </PageLayout>
</template>

This is conceptually similar to React's component composition:

function MyComponent() {
  return (
    <PageLayout>
      <Card>
        <CardContent>Hello world!</CardContent>
      </Card>
    </PageLayout>
  );
}

Reactivity & State Management

Reactivity Fundamentals

Vue's reactivity system is more granular than React's:

<script setup>
  import { ref, reactive, computed } from "vue";

  // Similar to: const [count, setCount] = useState(0)
  const count = ref(0);

  // Update state - different from React's setCount(count + 1)
  function increment() {
    count.value++; // Note: Use .value to get/set ref values
  }

  // Similar to a more complex useState object
  const user = reactive({
    name: "John",
    age: 30,
  });

  // Similar to useMemo, but cleaner syntax
  const doubleCount = computed(() => count.value * 2);
</script>

See our Login.vue for practical examples of state management.

Key Differences from React

1. Direct mutations: In Vue, you directly mutate state with count.value++, whereas React requires setCount(count + 1)
2. Automatic tracking: Vue automatically tracks dependencies, whereas React requires explicit dependency arrays
3. Computed properties: Vue provides computed() for derived state, which is cleaner than React's useMemo()

Template Syntax vs JSX

Vue Templates vs React JSX

Vue uses an HTML-based template syntax, while React uses JSX:

Concept	Vue	React
Attributes	<div :class="myClass">	<div className={myClass}>
Events	<button @click="handleClick">	<button onClick={handleClick}>
Conditional	<div v-if="showDiv">	{showDiv && <div>}
Loops	<div v-for="item in items">	{items.map(item => <div>)}
Text	<div>{{ message }}</div>	<div>{message}</div>

Examples in Our Codebase

Check out these components for real-world examples:

• Dashboard.vue - Lists and conditionals
• Navigation.vue - Router links and template basics

Routing

Vue Router is similar to React Router but with some syntax differences:

Route Configuration

// Vue Router (in main.ts)
const router = createRouter({
  history: createWebHistory(),
  routes: [
    {
      path: "/",
      component: () => import("./pages/Dashboard.vue"),
    },
    // More routes...
  ],
});

// React Router equivalent
const router = createBrowserRouter([
  {
    path: "/",
    element: <Dashboard />,
  },
  // More routes...
]);

See our fully commented main.ts for the complete router setup.

Router Links

<!-- Vue -->
<router-link to="/about" active-class="active">About</router-link>

<!-- React -->
<NavLink to="/about" activeClassName="active">About</NavLink>

Examples can be found in Navigation.vue.

Lifecycle Hooks

Vue's Composition API lifecycle hooks compared to React's:

Vue	React	Description
onMounted(() => {})	useEffect(() => {}, [])	Runs once after component mounts
onUpdated(() => {})	useEffect(() => {})	Runs after each update
onUnmounted(() => {})	useEffect(() => { return () => {} }, [])	Cleanup when component unmounts
watch(dep, callback)	useEffect(() => {}, [dep])	Watch for changes in specific dependencies

Example in Our Codebase

<script setup>
  import { onMounted, onUnmounted } from "vue";

  // Similar to React's:
  // useEffect(() => {
  //   window.addEventListener('resize', handleResize);
  //   return () => window.removeEventListener('resize', handleResize);
  // }, []);
  onMounted(() => {
    window.addEventListener("resize", handleResize);
  });

  onUnmounted(() => {
    window.removeEventListener("resize", handleResize);
  });
</script>

See PageLayout.vue for a practical lifecycle example.

Styling & UI Components

Global vs Component Styles

In our project, we use:

• Tailwind CSS for utility classes (similar to React)
• Global styles in transitions.css
• Component-specific styles can be added in a <style> block in .vue files

UI Component Library

We use shadcn-vue, which is similar to shadcn/ui in React:

<script setup>
  import { Card, CardHeader, CardContent } from "@/components/ui/card";
  import { Button } from "@/components/ui/button";
</script>

<template>
  <Card>
    <CardHeader>
      <h2>Card Title</h2>
    </CardHeader>
    <CardContent>
      <p>Card content</p>
      <Button>Click me</Button>
    </CardContent>
  </Card>
</template>

See Login.vue and Dashboard.vue for examples of UI component usage.

Additional Resources

Official Vue Documentation

• Vue.js Official Guide
• Vue Router
• Composition API

Vue for React Developers

• Vue for React Developers
• Vue vs React: Key Differences

Our Well-Commented Files

• App.vue - Root component
• main.ts - App initialization & routing
• PageLayout.vue - Layout with lifecycle methods
• Navigation.vue - Router navigation
• Login.vue - Forms and event handling

Conclusion

Vue and React share many concepts but differ in implementation details. Vue's template syntax might feel more HTML-like, while its reactivity system is more fine-grained than React's. With the mental models provided in this guide, you should be able to navigate the Vue codebase more confidently.

Remember that Vue's Composition API (using <script setup>) is the modern approach that's quite similar to React hooks, making the transition between frameworks smoother.

Happy coding!