The "astro:env/server" module is only available server-side. | Astro Lounge | Page 1

gloomy crater May 10, 2025, 3:04 PM

#

Getting The "astro:env/server" module is only available server-side.

and I am not sure where this is happening because I am not importing any server v ar in client but I am using Astro actions

somber matrixBOT May 10, 2025, 3:04 PM

#

Hi @gloomy crater. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

You're encountering the "ServerOnlyModule" error, which occurs when you try to access a server-only module from client-side code. This error specifically mentions "astro:env/server", which contains environment variables that are only meant to be used on the server.

Why this happens

The error occurs because somewhere in your code, you're trying to access server-side environment variables in client-side code. This can happen in several ways:

Direct imports in client components or scripts
Indirect imports through other modules
When using Astro Actions, which require server-side rendering

How to fix it

Since you're using Astro Actions, it's important to note that Actions require server-side rendering. According to the documentation:

Your project must have a server output to create backend functions with Actions. Actions Without Server Output Error

Here are steps to resolve this issue:

Check your imports: Make sure you're only importing from "astro:env/client" in client-side code, not "astro:env/server".
Enable SSR: Ensure you have server-side rendering enabled and an adapter installed:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import someAdapter from '@astrojs/some-adapter';

export default defineConfig({
  output: 'server', // Enable SSR
  adapter: someAdapter(), // Add an appropriate adapter
});

Use the correct environment variables: For client-side code, only use environment variables defined with context: "client" in your schema:

// astro.config.mjs
import { defineConfig, envField } from "astro/config";

#

export default defineConfig({
env: {
schema: {
// This can be used on client
PUBLIC_API_URL: envField.string({ context: "client", access: "public" }),
// This can only be used on server
API_SECRET: envField.string({ context: "server", access: "secret" }),
}
}
})


4. **Check component directives**: If you're using UI framework components, ensure they have the appropriate client directives if they need to access client-side environment variables.

Remember that the `astro:env` module can only be used inside the Astro context (middleware, routes, components) and not in configuration files or scripts [Limitations](<https://docs.astro.build/en/guides/environment-variables/#limitations>).

If you're still having trouble locating the issue, you might need to check all your imports and component usage to find where server-side environment variables might be leaking into client-side code.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------

#

@gloomy crater Kapa.ai is still learning and improving, please let me know how I did by reacting below.

gloomy crater May 10, 2025, 3:13 PM

#

@somber matrix I am getting

[astro-island] Error hydrating /src/components/auth/LoginForm.vue Error: [astro:action] defineAction() unexpectedly used on the client.

somber matrixBOT May 10, 2025, 3:13 PM

#

Let me check the knowledge base for you again. One moment! :books:

#

I see you're encountering an error with hydrating a Vue component that's using Astro actions. The specific error is:

[astro-island] Error hydrating /src/components/auth/LoginForm.vue Error: [astro:action] `defineAction()` unexpectedly used on the client.

This error occurs because you're trying to use defineAction() directly in your client-side Vue component. The defineAction() function is meant to be used only on the server side, specifically in your src/actions/index.ts file.

How to fix this issue

Don't import defineAction() in client components: The defineAction() function should only be used in your src/actions/index.ts file to define server-side actions.
Use the actions object instead: In your client components (like your Vue component), you should import and use the actions object from astro:actions, not the defineAction() function.

Here's how to properly use actions in a client component:

// In your Vue component
import { actions } from 'astro:actions';

// Then call your action like this:
const { data, error } = await actions.yourActionName(params);

As explained in the Actions Basic Usage documentation, you should:

Define your actions in src/actions/index.ts using defineAction()
Import and use the actions object in your client components to call those actions

Remember that Astro components are HTML-only templating components with no client-side runtime. If you're using a framework component like Vue with a client: directive, you need to follow the proper pattern for using actions in those components.

If you need more specific help, consider sharing your Vue component code so I can provide more targeted assistance.

#

Hope this helps resolve your hydration error!

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@gloomy crater Kapa.ai is still learning and improving, please let me know how I did by reacting below.

gloomy crater May 10, 2025, 3:15 PM

#

@somber matrix How to get in my frontend the type of the schema? i.e.

async function handleSubmit(fields: ??) using actions

somber matrixBOT May 10, 2025, 3:15 PM

#

Let me check the knowledge base for you again. One moment! :books:

#

I understand you want to know how to properly type the fields parameter in your handleSubmit function when using Astro Actions. Let me show you how to get the correct types for your action inputs in the frontend.

When using Astro Actions, you can leverage TypeScript to get type safety for your action inputs. Here's how to do it:

Getting Types for Action Inputs

Since you're using actions, you can infer the input type from your action definition. The TypeScript compiler will automatically infer the correct type based on the Zod schema you defined in your action.

Here's an example of how to type your handleSubmit function:

import { actions } from 'astro:actions';
import type { ComponentProps } from 'astro/types';

// Infer the input type from the action
type MyActionInput = Parameters<typeof actions.myAction>[0];

async function handleSubmit(fields: MyActionInput) {
  const { data, error } = await actions.myAction(fields);
  // ...
}

The Parameters<typeof actions.myAction>[0] utility type extracts the type of the first parameter of your action function, which corresponds to the input type defined by your Zod schema.

Alternative Approach

If you're working with form data, you can also define your types explicitly:

import { z } from 'astro:schema';

// Define the same schema as in your action
const inputSchema = z.object({
  email: z.string().email(),
  password: z.string()
});

// Extract the type from the schema
type LoginFormData = z.infer<typeof inputSchema>;

async function handleSubmit(fields: LoginFormData) {
  const { data, error } = await actions.login(fields);
  // ...
}

Best Practices

For better type safety, it's recommended to use explicit type imports:

#

import type { Parameters } from 'typescript';
import { actions } from 'astro:actions';

This way, you avoid edge cases where Astro's bundler might incorrectly bundle your imported types as JavaScript.

Remember that you need to run astro sync or astro dev to generate the TypeScript types for your actions, as mentioned in the CLI documentation.

This approach will give you full type safety and autocompletion when working with Astro Actions in your frontend code.

Hope this helps with your TypeScript integration for Astro Actions!

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@gloomy crater Kapa.ai is still learning and improving, please let me know how I did by reacting below.

gloomy crater May 10, 2025, 3:18 PM

#

@somber matrix I am using vue so instead of it being fields.email it is fields.email.value, how to adapt the types for it?

somber matrixBOT May 10, 2025, 3:18 PM

#

Let me check the knowledge base for you again. One moment! :books:

#

I understand you're using Vue with Astro Actions and need to adapt the types to account for Vue's reactivity system where properties have a .value accessor.

In Vue, when you use the Composition API with ref(), properties become reactive objects with a .value property. This means you need to adjust your TypeScript types to reflect this structure.

Here's how you can adapt the types for Vue's reactivity system:

import { actions } from 'astro:actions';
import type { Ref } from 'vue';

// Get the base type from your action
type BaseActionInput = Parameters<typeof actions.yourAction>[0];

// Create a Vue reactive version of the type
type VueReactiveForm = {
  [K in keyof BaseActionInput]: Ref<BaseActionInput[K]>
};

// Now use this type in your submit handler
async function handleSubmit(fields: VueReactiveForm) {
  // Convert the Vue refs back to plain values for the action
  const plainData = Object.fromEntries(
    Object.entries(fields).map(([key, ref]) => [key, ref.value])
  );
  
  const { data, error } = await actions.yourAction(plainData as BaseActionInput);
  // ...
}

Alternatively, if you're using a form with Vue, you might want to extract the values before passing them to your action:

import { actions } from 'astro:actions';
import { ref } from 'vue';

// Define your form fields as refs
const email = ref('');
const password = ref('');

async function handleSubmit() {
  // Extract values from refs before sending to the action
  const formData = {
    email: email.value,
    password: password.value
  };
  
  const { data, error } = await actions.login(formData);
  // ...
}

When working with form data in Vue, you can also use the FormData API directly:

#

async function handleSubmit(e: SubmitEvent) {
  e.preventDefault();
  const formData = new FormData(e.target as HTMLFormElement);
  const { error } = await actions.yourAction(formData);
  
  if (error) {
    // Handle errors
    if (isInputError(error)) {
      // Access field-specific errors
      console.log(error.fields.email);
    }
  }
}

This approach is shown in the Build forms with API routes documentation for Vue components.

Remember that when using Astro Actions with Vue, you need to ensure your component has the appropriate client directive (like `client:load`) to enable hydration.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@gloomy crater Kapa.ai is still learning and improving, please let me know how I did by reacting below.

gloomy crater May 10, 2025, 3:26 PM

#

@somber matrix in this logout.ts action my contxt.locals is empty there is no user nor jwt, why?

import { defineAction } from "astro:actions";
import { deleteAuthCookie } from "@/lib/cookies";
export const logout = defineAction({
  handler: async (_input, context) => {
    if (!context.locals.user) {
      return { error: "User not logged in" };
    }

    deleteAuthCookie(context.cookies);

    return { success: "User logged out" };
  },
});

somber matrixBOT May 10, 2025, 3:26 PM

#

Let me check the knowledge base for you again. One moment! :books:

#

I can see you're having an issue with your logout action where context.locals is empty and doesn't contain the user or JWT information you expect. Let's explore why this might be happening.

Why `context.locals` Might Be Empty

There are several reasons why context.locals might be empty in your action:

Middleware not setting the user: The most common reason is that you don't have middleware that sets the user in locals before the action runs. Actions don't automatically populate locals with authentication data.
Session management: If you're using sessions, you might not have properly initialized or accessed the session data.
Cookie access: Your authentication might be cookie-based, but the cookie isn't being properly read before the action runs.

How to Fix This

Here's how you can ensure context.locals contains your user data:

1. Add Middleware to Set User Data

Create or update your middleware to check authentication and set the user in locals:

// src/middleware.ts
import { defineMiddleware } from "astro:middleware";
import { verifyJWT } from "@/lib/auth"; // Your JWT verification function

export const onRequest = defineMiddleware(async (context, next) => {
  // Get the auth cookie
  const token = context.cookies.get("your-auth-cookie-name")?.value;
  
  if (token) {
    try {
      // Verify the token and get user data
      const userData = await verifyJWT(token);
      
      // Set the user in locals
      context.locals.user = userData;
    } catch (error) {
      // Token invalid, don't set user
    }
  }
  
  return next();
});

2. Use Session API (if applicable)

If you're using Astro's session API (available since v5.7.0), you can store user data in the session:

// In your login handler
Astro.session?.set('user', userData);

#

// In your middleware or action
const user = await context.session?.get('user');


As mentioned in the [Sessions documentation](<https://docs.astro.build/en/guides/sessions/#interacting-with-session-data>), you can access session data in actions via `context.session`.

### 3. Check Your Authentication Flow

Make sure your authentication flow is properly setting up the user before the action runs:

1. User logs in → JWT/cookie is set
2. Middleware runs on subsequent requests → verifies JWT/cookie and sets `context.locals.user`
3. Action runs with populated `context.locals`

## Important Notes About `locals`

Remember that in Astro v5+, you can't completely replace the `locals` object. Instead, you need to add properties to it:

```typescript
// Correct way to add to locals
context.locals.user = userData;

// Incorrect way (will cause an error)
context.locals = { user: userData };

As mentioned in the upgrade guide to v5, you must append values to the existing locals object without deleting it.

If you need more specific help, consider sharing your authentication setup (middleware, login action, etc.) so I can provide more targeted assistance.

#The "astro:env/server" module is only available server-side.

Why this happens

How to fix it

How to fix this issue

Hope this helps resolve your hydration error!

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Getting Types for Action Inputs

Alternative Approach

Best Practices

Hope this helps with your TypeScript integration for Astro Actions!

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Remember that when using Astro Actions with Vue, you need to ensure your component has the appropriate client directive (like `client:load`) to enable hydration.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Why `context.locals` Might Be Empty

How to Fix This

1. Add Middleware to Set User Data

2. Use Session API (if applicable)

Hope this helps you resolve your issue with the empty `context.locals`!

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#The "astro:env/server" module is only available server-side.

Why this happens

How to fix it

How to fix this issue

Hope this helps resolve your hydration error!

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Getting Types for Action Inputs

Alternative Approach

Best Practices

Hope this helps with your TypeScript integration for Astro Actions!

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Remember that when using Astro Actions with Vue, you need to ensure your component has the appropriate client directive (like client:load) to enable hydration.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Why context.locals Might Be Empty

How to Fix This

1. Add Middleware to Set User Data

2. Use Session API (if applicable)

Hope this helps you resolve your issue with the empty context.locals!

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Remember that when using Astro Actions with Vue, you need to ensure your component has the appropriate client directive (like `client:load`) to enable hydration.

Why `context.locals` Might Be Empty

Hope this helps you resolve your issue with the empty `context.locals`!