How do I pass a server variable to client side JS in astro?

Astro is a high-performance static site generator (SSG) widely adopted in modern web development. Its core advantage lies in combining Server-Side Rendering (SSR) with static generation to enhance page load speed and SEO performance. However, when building dynamic applications, developers frequently need to pass server-generated variables (such as configuration data, API responses, or environment parameters) to client-side JavaScript to implement interactive logic. This article provides an in-depth analysis of professional methods for passing server variables to client-side JavaScript in Astro, covering technical principles, code examples, and best practices to help developers avoid common pitfalls and optimize application performance.

Main Content

1. Overview of Astro's Variable Passing Mechanism

Astro's build process is divided into server-side (Server) and client-side (Client) phases. The server handles static resource generation and dynamic data, while the client manages interactive logic. Passing server variables requires specific mechanisms in Astro to ensure data is correctly injected into the client during the build process. The core principle is: Set variables during the server-side rendering phase and expose them to the frontend via client-side scripts. This differs from traditional frameworks (such as React), where Astro defaults to static generation, requiring explicit configuration to support data passing.

Key considerations:

• Avoid unnecessary requests: Directly passing variables reduces client-side API calls, improving performance.
• Security considerations: Server variables should only be used for non-sensitive data (e.g., configuration); sensitive data requires secure handling mechanisms.
• Build-time determinism: Variables are determined during the build phase, eliminating the need for additional client-side requests.

2. Core Method: Injecting via <script> Tags

This is Astro's recommended simple approach for basic variable passing. During server-side generation, variables are directly injected into client-side scripts using <script> tags. This method requires no additional components and is suitable for lightweight scenarios.

Technical principle: Astro merges server-side variables into client-side <script> tags during the build process, allowing access via window or module scope.

Code example:

In src/pages/index.astro:

astro
---
// Server-side variable definition: set via frontmatter or component logic
---

<!-- Server-side rendering phase: inject variables -->
<script type="module">
  // Access server-side variables via Astro.props (ensure declared in component)
  const { serverData } = Astro.props;

  // Mount variables to global window object (optional)
  window.clientData = {
    ...serverData,
    // Add client-specific data
    clientVersion: 'v2.0'
  };
</script>

<!-- Regular HTML content -->
<div>
  <h1>Welcome!</h1>
  <p>Server data example: {serverData.greeting}</p>
</div>

Practical recommendations:

• Use only for non-dynamic data: Avoid passing variables that change in real-time to prevent client-side logic conflicts.
• Performance optimization: Use this method for small data sets; for large data, handle via data attributes or pageData.

3. Advanced Method: Leveraging pageData and Component Properties

For complex scenarios (e.g., route parameters or server-side computed data), Astro provides the pageData mechanism. Server-side variables can be directly used in client-side components via export const pageData or Astro.props.

Technical principle: pageData is preprocessed during the build phase, allowing client-side access through Astro.props. This is ideal for scenarios requiring data processing within components.

Code example:

In src/pages/blog/[slug].astro:

astro
---
// Server-side variables: set via component logic
export const pageData = {
  title: 'Article Title',
  content: 'Server-generated content',
  // Add route parameters
  slug: Astro.params.slug
};
---

<!-- Client-side script: access pageData -->
<script type="module">
  // Access directly in client-side components
  const { pageData } = Astro.props;
  console.log('Page data:', pageData);

  // Add client-side logic
  if (pageData.isPreview) {
    document.body.style.backgroundColor = 'yellow';
  }
</script>

<!-- Render content using data -->
<article>
  <h2>{pageData.title}</h2>
  <p>{pageData.content}</p>
</article>

Practical recommendations:

• Avoid circular dependencies: Ensure pageData is generated only on the server; client-side should not recompute it.
• Validate data types: Check variable types on the client (e.g., if (typeof pageData.slug === 'string')) to prevent type errors.

4. Special Scenario: Passing Global Variables via astro Configuration

For application-level variables (e.g., environment configurations), pass them via the astro configuration file. This method is ideal for sharing data across pages.

Technical principle: Define global variables in src/astro.config.mjs, injecting them into all pages' <script> tags during the build process.

Code example:

In src/astro.config.mjs:

javascript
export default {
  site: 'https://example.com',
  // Define global variables (effective during server-side rendering)
  integrations: [
    // Pass variables via integration plugin
    function () {
      return {
        name: 'global-config',
        render: ({ props }) => {
          props.globalData = {
            apiUrl: 'https://api.example.com/v1',
            theme: 'dark'
          };
        }
      };
    }
  ]
};

Access in src/pages/index.astro:

astro
<script type="module">
  // Access global variables on the client
  const { globalData } = Astro.props;
  console.log('Global configuration:', globalData);
</script>

Practical recommendations:

• Use only for static data: globalData must be determined during the build phase to avoid dynamic changes.
• Performance impact: Large global data may increase build time; keep variables minimal.

5. Common Pitfalls and Solutions

In practice, developers often encounter these issues; address them proactively:

• Issue: Variables not properly passed

  • Cause: Server-side variables not exposed via Astro.props, or client-side access incorrect.
  • Solution: Explicitly set variables on the server (e.g., export const pageData) and access via Astro.props on the client.

• Issue: Performance bottlenecks

  • Cause: Large data volumes injected via <script>, slowing client-side parsing.
  • Solution: Use data attributes for small data (e.g., data-server-data='{...}') or implement pagination.

• Issue: Security risks

  • Cause: Direct exposure of sensitive data (e.g., user credentials) to the client.
  • Solution: Filter sensitive information on the server, passing only necessary fields (e.g., const { id } = serverData;).

Best practices summary:

• Prioritize <script> tags: Simple and efficient for most scenarios.
• Combine pageData: Handle complex logic while ensuring build-time determinism.
• Avoid redundant client-side requests: Use passed data directly instead of initiating new API calls.

Conclusion

Passing server variables to client-side JavaScript is a critical step in building dynamic applications with Astro. This article thoroughly analyzes methods like <script> tags, pageData, and astro configuration, providing reliable and detailed implementation strategies. Practical experience shows that correctly passing variables significantly boosts application performance and reduces client-side request overhead. Developers should choose appropriate methods based on project needs and strictly adhere to security guidelines—such as passing only necessary data and avoiding dynamic variable pollution. With Astro 2.0 maturing, these mechanisms will continue to optimize; we recommend staying updated with official documentation (Astro Documentation) for the latest guidance. Mastering these techniques not only enhances development efficiency but also enables the creation of high-performance, maintainable modern web applications.

Key reminder: In Astro projects, always prioritize passing variables during the server-side rendering phase to ensure client-side logic relies on build-time-determined data. For complex scenarios, consider extending capabilities with Astro plugins like @astrojs/image or @astrojs/preprocess.

​