create-react-starter-kit 1.0.0

package/templates/src/features/feedback/FeedbackForm.tsx.ejs

@@ -0,0 +1,373 @@
+<% if (forms === 'react-hook-form') { -%>
+import { useForm } from 'react-hook-form';
+<% if (validation === 'zod') { -%>
+import { zodResolver } from '@hookform/resolvers/zod';
+import { feedbackSchema<% if (isTypeScript) { %>, type FeedbackValues<% } %> } from '@/lib/validation';
+<% } else if (isTypeScript) { -%>
+import type { FeedbackValues } from '@/lib/validation';
+<% } -%>
+<% } else if (forms === 'formik') { -%>
+import { Formik, Form, Field, ErrorMessage } from 'formik';
+<% if (validation === 'yup') { -%>
+import { feedbackSchema } from '@/lib/validation';
+<% } else if (validation === 'zod') { -%>
+import { feedbackSchema } from '@/lib/validation';
+<% } -%>
+<% if (isTypeScript) { -%>
+import type { FeedbackValues } from '@/lib/validation';
+<% } -%>
+<% } else if (forms === 'tanstack-form') { -%>
+import { useForm } from '@tanstack/react-form';
+<% if (validation !== 'none') { -%>
+import { feedbackSchema } from '@/lib/validation';
+<% } -%>
+<% if (isTypeScript) { -%>
+import type { FeedbackValues } from '@/lib/validation';
+<% } -%>
+<% } else { -%>
+import { useState } from 'react';
+<% if (validation === 'none') { -%>
+import { validateFeedback<% if (isTypeScript) { %>, type FeedbackValues<% } %> } from '@/lib/validation';
+<% } else { -%>
+import { feedbackSchema<% if (isTypeScript) { %>, type FeedbackValues<% } %> } from '@/lib/validation';
+<% } -%>
+<% } -%>
+import { createFeedback } from '@/services/api';
+import { useToast } from '@/components/ui/Toast';
+import { UiButton } from '@/components/ui/UiButton';
+
+const defaults<% if (isTypeScript) { %>: FeedbackValues<% } %> = {
+  name: '',
+  email: '',
+  message: '',
+};
+
+export function FeedbackForm() {
+  const { push } = useToast();
+
+<% if (forms === 'react-hook-form') { -%>
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors, isSubmitting },
+  } = useForm<% if (isTypeScript) { %><FeedbackValues><% } %>({
+    defaultValues: defaults,
+<% if (validation === 'zod') { -%>
+    resolver: zodResolver(feedbackSchema),
+<% } -%>
+  });
+
+  const onSubmit = async (values<% if (isTypeScript) { %>: FeedbackValues<% } %>) => {
+<% if (validation === 'yup') { -%>
+    await feedbackSchema.validate(values, { abortEarly: false });
+<% } else if (validation === 'valibot') { -%>
+    const { parse } = await import('valibot');
+    parse(feedbackSchema, values);
+<% } else if (validation === 'joi') { -%>
+    const result = feedbackSchema.validate(values, { abortEarly: false });
+    if (result.error) {
+      throw result.error;
+    }
+<% } -%>
+    await createFeedback(values);
+    push('Feedback submitted (demo API)', 'success');
+    reset();
+  };
+
+  return (
+    <article className="panel">
+      <header className="panel-header">
+        <h2>Forms & validation</h2>
+        <p>
+          <%= stackLabels.forms %>
+<% if (validation !== 'none') { -%>
+          {' '}
+          + <%= stackLabels.validation %>
+<% } -%>
+        </p>
+      </header>
+      <form className="feedback-form" onSubmit={handleSubmit(onSubmit)} noValidate>
+        <label>
+          Name
+          <input {...register('name')} placeholder="Ada Lovelace" />
+          {errors.name && <span className="field-error">{errors.name.message}</span>}
+        </label>
+        <label>
+          Email
+          <input type="email" {...register('email')} placeholder="ada@example.com" />
+          {errors.email && <span className="field-error">{errors.email.message}</span>}
+        </label>
+        <label>
+          Message
+          <textarea rows={4} {...register('message')} placeholder="What should we improve?" />
+          {errors.message && <span className="field-error">{errors.message.message}</span>}
+        </label>
+        <UiButton type="submit" disabled={isSubmitting}>
+          {isSubmitting ? 'Sending…' : 'Send feedback'}
+        </UiButton>
+      </form>
+      <p className="panel-note">
+        <strong>When to use:</strong> complex forms with validation and async submit.
+        <br />
+        <strong>Best practice:</strong> keep schemas in <code>src/lib</code> and reuse across client/server.
+      </p>
+    </article>
+  );
+<% } else if (forms === 'formik') { -%>
+  return (
+    <article className="panel">
+      <header className="panel-header">
+        <h2>Forms & validation</h2>
+        <p>
+          <%= stackLabels.forms %>
+<% if (validation !== 'none') { -%>
+          {' '}
+          + <%= stackLabels.validation %>
+<% } -%>
+        </p>
+      </header>
+      <Formik
+        initialValues={defaults}
+<% if (validation === 'yup') { -%>
+        validationSchema={feedbackSchema}
+<% } -%>
+        onSubmit={async (values, helpers) => {
+<% if (validation === 'zod') { -%>
+          feedbackSchema.parse(values);
+<% } -%>
+          await createFeedback(values);
+          push('Feedback submitted (demo API)', 'success');
+          helpers.resetForm();
+        }}
+      >
+        {({ isSubmitting }) => (
+          <Form className="feedback-form" noValidate>
+            <label>
+              Name
+              <Field name="name" placeholder="Ada Lovelace" />
+              <ErrorMessage name="name" component="span" className="field-error" />
+            </label>
+            <label>
+              Email
+              <Field name="email" type="email" placeholder="ada@example.com" />
+              <ErrorMessage name="email" component="span" className="field-error" />
+            </label>
+            <label>
+              Message
+              <Field as="textarea" rows={4} name="message" placeholder="What should we improve?" />
+              <ErrorMessage name="message" component="span" className="field-error" />
+            </label>
+            <UiButton type="submit" disabled={isSubmitting}>
+              {isSubmitting ? 'Sending…' : 'Send feedback'}
+            </UiButton>
+          </Form>
+        )}
+      </Formik>
+      <p className="panel-note">
+        <strong>When to use:</strong> form-heavy screens with Formik's render/props model.
+        <br />
+        <strong>Best practice:</strong> prefer Yup/Zod schemas over ad-hoc validators.
+      </p>
+    </article>
+  );
+<% } else if (forms === 'tanstack-form') { -%>
+  const form = useForm({
+    defaultValues: defaults,
+    onSubmit: async ({ value }) => {
+<% if (validation === 'zod') { -%>
+      feedbackSchema.parse(value);
+<% } else if (validation === 'yup') { -%>
+      await feedbackSchema.validate(value);
+<% } else if (validation === 'valibot') { -%>
+      const { parse } = await import('valibot');
+      parse(feedbackSchema, value);
+<% } else if (validation === 'joi') { -%>
+      const result = feedbackSchema.validate(value);
+      if (result.error) throw result.error;
+<% } -%>
+      await createFeedback(value);
+      push('Feedback submitted (demo API)', 'success');
+      form.reset();
+    },
+  });
+
+  return (
+    <article className="panel">
+      <header className="panel-header">
+        <h2>Forms & validation</h2>
+        <p>
+          <%= stackLabels.forms %>
+<% if (validation !== 'none') { -%>
+          {' '}
+          + <%= stackLabels.validation %>
+<% } -%>
+        </p>
+      </header>
+      <form
+        className="feedback-form"
+        onSubmit={(e) => {
+          e.preventDefault();
+          e.stopPropagation();
+          void form.handleSubmit();
+        }}
+      >
+        <form.Field name="name">
+          {(field) => (
+            <label>
+              Name
+              <input
+                value={field.state.value}
+                onBlur={field.handleBlur}
+                onChange={(e) => field.handleChange(e.target.value)}
+                placeholder="Ada Lovelace"
+              />
+            </label>
+          )}
+        </form.Field>
+        <form.Field name="email">
+          {(field) => (
+            <label>
+              Email
+              <input
+                type="email"
+                value={field.state.value}
+                onBlur={field.handleBlur}
+                onChange={(e) => field.handleChange(e.target.value)}
+                placeholder="ada@example.com"
+              />
+            </label>
+          )}
+        </form.Field>
+        <form.Field name="message">
+          {(field) => (
+            <label>
+              Message
+              <textarea
+                rows={4}
+                value={field.state.value}
+                onBlur={field.handleBlur}
+                onChange={(e) => field.handleChange(e.target.value)}
+                placeholder="What should we improve?"
+              />
+            </label>
+          )}
+        </form.Field>
+        <UiButton type="submit">Send feedback</UiButton>
+      </form>
+      <p className="panel-note">
+        <strong>When to use:</strong> headless, type-safe forms with fine-grained reactivity.
+        <br />
+        <strong>Best practice:</strong> validate at field and form boundaries with a shared schema.
+      </p>
+    </article>
+  );
+<% } else { -%>
+  const [values, setValues] = useState<% if (isTypeScript) { %><FeedbackValues><% } %>(defaults);
+  const [errors, setErrors] = useState<% if (isTypeScript) { %><Partial<Record<keyof FeedbackValues, string>>><% } %>({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const onSubmit = async (event<% if (isTypeScript) { %>: React.FormEvent<% } %>) => {
+    event.preventDefault();
+<% if (validation === 'none') { -%>
+    const nextErrors = validateFeedback(values);
+<% } else if (validation === 'zod') { -%>
+    const parsed = feedbackSchema.safeParse(values);
+    const nextErrors = parsed.success
+      ? {}
+      : Object.fromEntries(
+          parsed.error.issues.map((issue) => [String(issue.path[0]), issue.message]),
+        );
+<% } else if (validation === 'yup') { -%>
+    let nextErrors<% if (isTypeScript) { %>: Partial<Record<keyof FeedbackValues, string>><% } %> = {};
+    try {
+      await feedbackSchema.validate(values, { abortEarly: false });
+    } catch (err) {
+      if (err && typeof err === 'object' && 'inner' in err) {
+        nextErrors = Object.fromEntries(
+          (err<% if (isTypeScript) { %> as { inner: Array<{ path?: string; message: string }> }<% } %>).inner
+            .filter((e) => e.path)
+            .map((e) => [e.path, e.message]),
+        );
+      }
+    }
+<% } else if (validation === 'joi') { -%>
+    const result = feedbackSchema.validate(values, { abortEarly: false });
+    const nextErrors = result.error
+      ? Object.fromEntries(
+          result.error.details.map((d<% if (isTypeScript) { %>: { path: (string | number)[]; message: string }<% } %>) => [
+            String(d.path[0]),
+            d.message,
+          ]),
+        )
+      : {};
+<% } else { -%>
+    let nextErrors<% if (isTypeScript) { %>: Partial<Record<keyof FeedbackValues, string>><% } %> = {};
+    try {
+      const { parse } = await import('valibot');
+      parse(feedbackSchema, values);
+    } catch (err) {
+      nextErrors = { message: err instanceof Error ? err.message : 'Invalid form' };
+    }
+<% } -%>
+    setErrors(nextErrors);
+    if (Object.keys(nextErrors).length) return;
+    setIsSubmitting(true);
+    try {
+      await createFeedback(values);
+      push('Feedback submitted (demo API)', 'success');
+      setValues(defaults);
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <article className="panel">
+      <header className="panel-header">
+        <h2>Forms & validation</h2>
+        <p>Native form controls<% if (validation !== 'none') { %> + <%= stackLabels.validation %><% } %></p>
+      </header>
+      <form className="feedback-form" onSubmit={onSubmit} noValidate>
+        <label>
+          Name
+          <input
+            value={values.name}
+            onChange={(e) => setValues((v) => ({ ...v, name: e.target.value }))}
+            placeholder="Ada Lovelace"
+          />
+          {errors.name && <span className="field-error">{errors.name}</span>}
+        </label>
+        <label>
+          Email
+          <input
+            type="email"
+            value={values.email}
+            onChange={(e) => setValues((v) => ({ ...v, email: e.target.value }))}
+            placeholder="ada@example.com"
+          />
+          {errors.email && <span className="field-error">{errors.email}</span>}
+        </label>
+        <label>
+          Message
+          <textarea
+            rows={4}
+            value={values.message}
+            onChange={(e) => setValues((v) => ({ ...v, message: e.target.value }))}
+            placeholder="What should we improve?"
+          />
+          {errors.message && <span className="field-error">{errors.message}</span>}
+        </label>
+        <UiButton type="submit" disabled={isSubmitting}>
+          {isSubmitting ? 'Sending…' : 'Send feedback'}
+        </UiButton>
+      </form>
+      <p className="panel-note">
+        <strong>When to use:</strong> simple forms without a dedicated form library.
+        <br />
+        <strong>Best practice:</strong> graduate to a form library once fields or validation grow.
+      </p>
+    </article>
+  );
+<% } -%>
+}

package/templates/src/features/posts/PostsPanel.tsx.ejs

@@ -0,0 +1,91 @@
+<% if (serverState === 'tanstack-query') { -%>
+import { useQuery } from '@tanstack/react-query';
+import { fetchPosts } from '@/services/api';
+<% } else if (serverState === 'swr') { -%>
+import useSWR from 'swr';
+<% } else if (serverState === 'rtk-query') { -%>
+import { useGetPostsQuery } from '@/store/postsApi';
+<% } else { -%>
+import { useEffect, useState } from 'react';
+import { fetchPosts } from '@/services/api';
+<% } -%>
+
+export function PostsPanel() {
+<% if (serverState === 'tanstack-query') { -%>
+  const { data, isLoading, error, refetch, isFetching } = useQuery({
+    queryKey: ['posts'],
+    queryFn: fetchPosts,
+  });
+<% } else if (serverState === 'swr') { -%>
+  const { data, error, isLoading, isValidating, mutate } = useSWR('/posts?_limit=5');
+  const isFetching = isValidating;
+  const refetch = () => mutate();
+<% } else if (serverState === 'rtk-query') { -%>
+  const { data, isLoading, error, refetch, isFetching } = useGetPostsQuery();
+<% } else { -%>
+  const [data, setData] = useState<% if (isTypeScript) { %><Awaited<ReturnType<typeof fetchPosts>> | null><% } %>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<% if (isTypeScript) { %><Error | null><% } %>(null);
+  const [isFetching, setIsFetching] = useState(false);
+
+  const load = async () => {
+    setIsFetching(true);
+    setError(null);
+    try {
+      const posts = await fetchPosts();
+      setData(posts);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Failed to load'));
+    } finally {
+      setIsLoading(false);
+      setIsFetching(false);
+    }
+  };
+
+  useEffect(() => {
+    void load();
+  }, []);
+
+  const refetch = () => void load();
+<% } -%>
+
+  return (
+    <article className="panel">
+      <header className="panel-header">
+        <h2>Server state</h2>
+        <p>
+          <%= stackLabels.serverState === 'None' ? 'Manual fetch via ' + stackLabels.apiLayer : stackLabels.serverState %>{' '}
+          · JSONPlaceholder posts
+        </p>
+      </header>
+
+      <div className="panel-toolbar">
+        <button type="button" className="ui-button" onClick={() => void refetch()} disabled={isFetching}>
+          {isFetching ? 'Refreshing…' : 'Refresh'}
+        </button>
+      </div>
+
+      {isLoading && <p className="muted">Loading posts…</p>}
+      {error && (
+        <p className="error-text">
+          {error instanceof Error ? error.message : 'Request failed'}
+        </p>
+      )}
+      {data && (
+        <ul className="post-list">
+          {data.map((post<% if (isTypeScript) { %>: { id: number; title: string }<% } %>) => (
+            <li key={post.id}>
+              <strong>#{post.id}</strong> {post.title}
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <p className="panel-note">
+        <strong>When to use:</strong> remote data with caching, retries, and refetch rules.
+        <br />
+        <strong>Best practice:</strong> treat server cache separately from UI/client state.
+      </p>
+    </article>
+  );
+}

package/templates/src/hooks/useMounted.ts.ejs

@@ -0,0 +1,15 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Returns true after the component has mounted on the client.
+ * Useful for avoiding hydration mismatches with client-only UI.
+ */
+export function useMounted() {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  return mounted;
+}

package/templates/src/lib/cn.ts.ejs

@@ -0,0 +1,12 @@
+<% if (uiLibrary === 'shadcn') { -%>
+import { clsx<% if (isTypeScript) { %>, type ClassValue<% } %> } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs<% if (isTypeScript) { %>: ClassValue[]<% } %>) {
+  return twMerge(clsx(inputs));
+}
+<% } else { -%>
+export function cn(...parts<% if (isTypeScript) { %>: Array<string | false | null | undefined><% } %>) {
+  return parts.filter(Boolean).join(' ');
+}
+<% } -%>

package/templates/src/lib/monitoring.ts.ejs

@@ -0,0 +1,66 @@
+<% if (errorTracking === 'sentry') { -%>
+import * as Sentry from '@sentry/react';
+
+export function initMonitoring() {
+  const dsn = import.meta.env?.VITE_SENTRY_DSN;
+  if (!dsn) {
+    return;
+  }
+
+  Sentry.init({
+    dsn,
+    tracesSampleRate: 0.1,
+    environment: import.meta.env?.MODE ?? 'development',
+  });
+}
+<% } else if (errorTracking === 'bugsnag') { -%>
+import Bugsnag from '@bugsnag/js';
+import BugsnagPluginReact from '@bugsnag/plugin-react';
+
+export function initMonitoring() {
+  const apiKey = import.meta.env?.VITE_BUGSNAG_API_KEY;
+  if (!apiKey) {
+    return;
+  }
+
+  Bugsnag.start({
+    apiKey,
+    plugins: [new BugsnagPluginReact()],
+  });
+}
+<% } else if (errorTracking === 'logrocket') { -%>
+import LogRocket from 'logrocket';
+
+export function initMonitoring() {
+  const appId = import.meta.env?.VITE_LOGROCKET_APP_ID;
+  if (!appId) {
+    return;
+  }
+
+  LogRocket.init(appId);
+}
+<% } else if (errorTracking === 'datadog') { -%>
+import { datadogRum } from '@datadog/browser-rum';
+
+export function initMonitoring() {
+  const applicationId = import.meta.env?.VITE_DATADOG_APPLICATION_ID;
+  const clientToken = import.meta.env?.VITE_DATADOG_CLIENT_TOKEN;
+  if (!applicationId || !clientToken) {
+    return;
+  }
+
+  datadogRum.init({
+    applicationId,
+    clientToken,
+    site: import.meta.env?.VITE_DATADOG_SITE ?? 'datadoghq.com',
+    service: '<%= projectName %>',
+    sessionSampleRate: 100,
+    trackResources: true,
+    trackLongTasks: true,
+  });
+}
+<% } else { -%>
+export function initMonitoring() {
+  // Error tracking disabled for this scaffold.
+}
+<% } -%>

package/templates/src/lib/validation.ts.ejs

@@ -0,0 +1,81 @@
+<% if (validation === 'zod') { -%>
+import { z } from 'zod';
+
+export const feedbackSchema = z.object({
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+  email: z.string().email('Enter a valid email'),
+  message: z.string().min(10, 'Message must be at least 10 characters'),
+});
+
+<% if (isTypeScript) { -%>
+export type FeedbackValues = z.infer<typeof feedbackSchema>;
+<% } -%>
+<% } else if (validation === 'yup') { -%>
+import * as yup from 'yup';
+
+export const feedbackSchema = yup.object({
+  name: yup.string().min(2, 'Name must be at least 2 characters').required(),
+  email: yup.string().email('Enter a valid email').required(),
+  message: yup.string().min(10, 'Message must be at least 10 characters').required(),
+});
+
+<% if (isTypeScript) { -%>
+export type FeedbackValues = yup.InferType<typeof feedbackSchema>;
+<% } -%>
+<% } else if (validation === 'valibot') { -%>
+import * as v from 'valibot';
+
+export const feedbackSchema = v.object({
+  name: v.pipe(v.string(), v.minLength(2, 'Name must be at least 2 characters')),
+  email: v.pipe(v.string(), v.email('Enter a valid email')),
+  message: v.pipe(v.string(), v.minLength(10, 'Message must be at least 10 characters')),
+});
+
+<% if (isTypeScript) { -%>
+export type FeedbackValues = v.InferOutput<typeof feedbackSchema>;
+<% } -%>
+<% } else if (validation === 'joi') { -%>
+import Joi from 'joi';
+
+export const feedbackSchema = Joi.object({
+  name: Joi.string().min(2).required().messages({
+    'string.min': 'Name must be at least 2 characters',
+  }),
+  email: Joi.string().email({ tlds: false }).required().messages({
+    'string.email': 'Enter a valid email',
+  }),
+  message: Joi.string().min(10).required().messages({
+    'string.min': 'Message must be at least 10 characters',
+  }),
+});
+
+<% if (isTypeScript) { -%>
+export interface FeedbackValues {
+  name: string;
+  email: string;
+  message: string;
+}
+<% } -%>
+<% } else { -%>
+<% if (isTypeScript) { -%>
+export interface FeedbackValues {
+  name: string;
+  email: string;
+  message: string;
+}
+<% } -%>
+
+export function validateFeedback(values<% if (isTypeScript) { %>: FeedbackValues<% } %>) {
+  const errors<% if (isTypeScript) { %>: Partial<Record<keyof FeedbackValues, string>><% } %> = {};
+  if (!values.name || values.name.length < 2) {
+    errors.name = 'Name must be at least 2 characters';
+  }
+  if (!values.email || !values.email.includes('@')) {
+    errors.email = 'Enter a valid email';
+  }
+  if (!values.message || values.message.length < 10) {
+    errors.message = 'Message must be at least 10 characters';
+  }
+  return errors;
+}
+<% } -%>

package/templates/src/main.tsx.ejs

@@ -0,0 +1,22 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { AppProviders } from '@/app/providers';
+import { App } from '@/app/App';
+import { initMonitoring } from '@/lib/monitoring';
+import '@/styles/global.<%= styling === 'sass' && uiLibrary !== 'shadcn' ? 'scss' : 'css' %>';
+
+initMonitoring();
+
+const rootElement = document.getElementById('root');
+
+if (!rootElement) {
+  throw new Error('Root element #root not found');
+}
+
+createRoot(rootElement).render(
+  <StrictMode>
+    <AppProviders>
+      <App />
+    </AppProviders>
+  </StrictMode>,
+);